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
| Type | Location |
|---|---|
| Shared types | types/ or packages/types/ |
| Utilities | lib/ or utils/ (split by domain) |
| Config | config/ or root |
| Unit tests | Colocate: foo.test.ts next to foo.ts |
| E2E tests | e2e/ or tests/e2e/ |
| Mocks/fixtures | __mocks__/ or test/mocks/ |
Naming Conventions
| Type | Convention |
|---|---|
| Files | kebab-case.ts |
| Unit tests | *.test.ts |
| E2E tests | *.e2e.ts |
| Schemas | *.schema.ts |
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.tswith 50+ re-exports