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.ts with 50+ re-exports