Skip to content

Component Granularity

Metadata

  • Status: Accepted & Implemented
  • Date: 2025-12-20
  • Type: Architecture Decision Record (ADR)

The "Too Many Files" Concern

It is common to worry when a project expands from 5 large files to 30+ smaller ones. It can feel like the code is "scattered." However, in modern frontend architecture (especially React), file count is a poor proxy for complexity.

1. The Cognitive Load Argument

  • Centralized (Big Files):

    • Pro: You can use Ctrl+F to find everything in one place.
    • Con: To change a button color, you scroll past 500 lines of API logic, state management, and type definitions. You must "load" the entire component into your brain to ensure you don't break unrelated parts.
    • Limit: Once a file hits ~300-400 lines, it becomes a "God Component," difficult to test and maintain.

  • Decoupled (Many Files):

    • Pro: When working on DailyTotals, you only see code related to daily totals. You don't see the clipboard logic or the settings modal.
    • Con: You need to navigate the file tree more often.
    • Solution: Good IDE navigation (Go to Definition) makes file hopping instant, negating the "scattered" feeling.

2. The Separation of Concerns

We refactored Dashboard.tsx because it was violating the Single Responsibility Principle. It was doing three things:

  1. View: Rendering HTML/CSS.
  2. State: Managing complex objects (clipboard, layout preferences).
  3. Data: Fetching from APIs.

By splitting it:

  • useMeals.ts handles Data.
  • useLayoutPreference.ts handles State.
  • Dashboard.tsx handles View (Composition).
  • MealItem.tsx handles View (Atomic).

3. When to Split (Rule of Thumb)

Do not split just for the sake of it. Split when:

  1. Reusability: A piece of UI (like ProgressBar) is used in multiple places.
  2. Complexity: A component has too many useState or useEffect hooks (e.g., extracting useMealStaging).
  3. Frequency of Change: If you constantly edit the Logic but rarely touch the UI, they should probably be separate files.

4. Project Metrics (Post-Refactor)

  • Total Files: ~32 source files.
  • Largest File: Dashboard.tsx (~300 lines). This is still on the larger side but acceptable as a "Page" controller.
  • Average File: ~85 lines. This is the "Sweet Spot" – easy to read in a single screen without scrolling.

Conclusion

32 files for a production-grade React application is actually very lean. "Enterprise" apps often have thousands. The current structure strikes a balance: enough structure to be scalable, but flat enough to remain navigable.