code-organization

code-organization

Where each kind of code goes. Apply this every time you create a file or add a type, schema, helper, or constant. Don't inline them next to feature code and don't pile unrelated things into one file.

Layout

Each category gets its own dedicated folder. Files inside a folder are grouped by domain (e.g. user, post), not by individual symbol.

src/
  types/        type & interface definitions        types/user.ts
  schemas/      validation schemas (zod, yup, etc.) schemas/user.ts
  utils/        helper / utility functions          utils/format.ts
  constants/    constant values, enums, config      constants/routes.ts

Rules

1. One folder per category — types/, schemas/, utils/, constants/. A new type goes in types/, never inline in the file that uses it or alongside a component.

2. Group files by domain inside a folder. All user-related types live in types/user.ts; all user-related constants in constants/user.ts. Split a file once it covers clearly separate domains — not per symbol.

3. Functions get their own file. A reusable helper lives in utils/ in a file named for what it does (utils/format.ts, utils/slugify.ts). Keep one focused concern per file; don't accumulate a utils/index.ts junk drawer.

4. No barrel files. Do not add index.ts re-export barrels. Import directly from the specific file:

   import { formatDate } from "@/utils/format";   // ✓
   import { formatDate } from "@/utils";           // ✗ no barrel
   

   This keeps imports explicit and avoids circular-import and tree-shaking surprises.

5. Types vs schemas are separate concerns. types/ holds pure TypeScript type/interface declarations. schemas/ holds runtime validation schemas. If a type is derived from a schema, infer it in types/ and import the schema — keep the validator in schemas/.

Where does it go?

You're adding…	Folder	Example file
type / interface	types/	types/user.ts
validation / parse schema	schemas/	schemas/user.ts
pure helper function	utils/	utils/format.ts
constant, enum, config literal	constants/	constants/routes.ts
React component, route, feature code	feature dir	user/profile.tsx