How to Organize Features

Features are organized by domain, then by feature name. Every feature lives in src/features/<domain>/<feature>/.

Structure

src/features/
  notifications/
    notification-dropdown/
      notification-dropdown.tsx
      hooks/
        use-notification-dropdown.ts
    notification-list/
      notification-list.tsx
    hooks/
      use-unread-count.ts
  settings/
    profile-tab/
      profile-tab.tsx
    security-tab/
      security-tab.tsx

Rules

1. Always nest inside <domain>/<feature>/. Even single-file features get their own folder. src/features/settings/profile-tab/profile-tab.tsx, not src/features/settings/profile-tab.tsx.

2. Pages belong in src/routes/. Route files import feature components. Features never contain "page" files.

3. Hooks are scoped to where they're used:

   • Feature-level: <feature>/hooks/ when only that feature uses it
   • Domain-level: <domain>/hooks/ when shared across features in the same domain
   • Global: src/hooks/ when truly app-wide

4. No flat files at the domain level. Only shared folders like hooks/, types/, constants/.

5. Keep feature code colocated. Components, hooks, types, queries, schemas, and tests all live inside the feature folder they belong to. Don't move things to global components/ or hooks/ just because of file kind.

Adding a new feature

1. Create the folder: src/features/<domain>/<feature>/
2. Add your component: <feature>.tsx
3. Add hooks, types, or helpers in subfolders as needed
4. Import the component from a route file in src/routes/