Folder Structure

Core Principle: Colocation

Place code as close to where it’s relevant as possible. Things that change together should be located together.

Organization Approaches

Feature-Based (Recommended for Frontend)

Group by domain – all related code in one place:

src/features/
├── auth/
│   ├── components/
│   ├── hooks/
│   ├── auth.service.ts
│   └── auth.test.ts
├── users/
└── products/

Layer-Based (Common for Backend)

Group by technical layer:

src/
├── controllers/
├── services/
├── models/
├── routes/
└── middleware/

Monorepo

apps/           # Applications
├── web/
├── api/
packages/       # Shared libraries (by domain, not language)
├── types/
├── utils/
└── ui/

Where to Put Things

Naming Conventions

Anti-Patterns

• Catch-all files: Avoid utils.ts, helpers.ts – split by domain
• Deep nesting: Keep < 4 levels, use descriptive names instead
• Separated unit tests: Don’t put all in __tests__/ – colocate instead
• Language grouping: In monorepos, group by domain not language
• Bloated barrels: Avoid index.ts with 50+ re-exports