file-organization

File Organization

Structure codebases with many small, focused files organized by feature or domain. Target 200-400 lines per file, with 800 as a hard maximum.

When to Use

• Creating a new project or feature module
• A file exceeds 400 lines and needs splitting
• Deciding where to place new code
• Reviewing project structure for maintainability
• Setting up barrel exports or index files

Core Patterns

Feature-Based Organization (Preferred)

Group files by feature/domain, not by type. Each feature folder contains everything it needs:

src/
  auth/
    components/
      LoginForm.tsx
      SignupForm.tsx
    hooks/
      useAuth.ts
      useSession.ts
    services/
      auth.service.ts
      token.service.ts
    types.ts
    constants.ts
    index.ts              # barrel export

  users/
    components/
      UserProfile.tsx
      UserList.tsx
    hooks/
      useUser.ts
    services/
      user.service.ts
    types.ts
    index.ts

  shared/                 # Cross-cutting concerns only
    components/
      Button.tsx
      Modal.tsx
    hooks/
      useDebounce.ts
    utils/
      format.ts
      validation.ts

Compare with the type-based approach (avoid this):

# BAD: Type-based organization
src/
  components/             # 50+ files, mixed concerns
    LoginForm.tsx
    UserProfile.tsx
    Button.tsx
    OrderTable.tsx
  hooks/                  # Hard to find related code
    useAuth.ts
    useUser.ts
    useOrders.ts
  services/
    auth.service.ts
    user.service.ts

File Size Guidelines

Lines	Action
< 100	Fine, but check if the file is too granular
100-400	Ideal range for most files
400-600	Consider splitting if multiple concerns
600-800	Split into smaller modules
> 800	Must refactor — file is too large

Extract when you see:

• Multiple classes or major type groups in one file
• Utility functions unrelated to the file's primary purpose
• Sections separated by comment banners (// ===== Section =====)
• More than 5 exported functions from a single file