# Feature-first layouts — web, mobile and monorepo

> Verified 2026-09 against https://nextjs.org/docs/app/getting-started/project-structure , https://reactrouter.com/start/framework/routing , https://docs.expo.dev/router/basics/core-concepts/ and https://eslint.org/docs/latest/rules/no-restricted-imports. Shared by `react-architecture` and `react-native-architecture`; this is the only copy of the folder tree.

## 1. The rule in one paragraph

Group by feature, not by file type. A feature owns its components, hooks, API calls and domain logic; everything it exposes goes through `index.ts`. Route files are thin: they read params, call the feature's screen and nothing else. `shared/` holds code with no business meaning and never imports from `features/`. Dependencies point one way: `app → features → entities → shared`.

## 2. Feature slice (same in every framework)

```
features/orders/
├── components/        # OrderList.tsx, OrderRow.tsx — feature-private UI
├── hooks/             # useOrderFilters.ts
├── api/               # queries.ts (useOrders, useOrder), mutations.ts, keys.ts, *.server.ts for server-only code
├── model/             # order.ts (types, Zod schemas), pricing.ts (pure functions, unit-tested)
├── i18n/              # messages per locale (optional)
└── index.ts           # the public API: export { OrdersScreen } from './components/OrdersScreen'
```

- Inside a feature use relative imports; from outside import only `@/features/orders`.
- Two features need the same type or query → move it to `entities/<name>/` (domain objects shared across features), not to `shared/`.
- Tests sit next to the file (`OrderRow.test.tsx`); test helpers in `src/test/`.

## 3. Next.js 16 (App Router)

```
src/
├── app/                        # routing only
│   ├── layout.tsx              # providers, fonts, <html>
│   ├── (marketing)/page.tsx
│   ├── (app)/
│   │   ├── layout.tsx          # authenticated shell
│   │   └── orders/
│   │       ├── page.tsx        # export default async function Page() { return <OrdersScreen /> }
│   │       ├── loading.tsx
│   │       ├── error.tsx       # 'use client'
│   │       └── [id]/page.tsx
│   └── api/                    # route handlers (webhooks, BFF endpoints)
├── features/
├── entities/
├── shared/{ui,lib,hooks,config}
├── server/                     # db client, session, secrets — every file starts with import 'server-only'
└── proxy.ts                    # request pre-checks (Next.js 16; replaces middleware.ts)
```

Private folders (`_components`) and route groups (`(app)`) do not affect the URL; prefer `features/` over colocating large trees under `app/`.

## 4. React Router v8 framework mode

```
app/
├── root.tsx                    # document, providers, root ErrorBoundary
├── routes.ts                   # route config: index(), route(), layout(), prefix()
├── routes/
│   ├── home.tsx
│   ├── orders.tsx              # loader/action + default export that renders <OrdersScreen />
│   └── orders.$id.tsx
├── features/
├── entities/
└── shared/
react-router.config.ts          # ssr: true | false, prerender
```

Server-only modules use the `.server.ts` suffix (the compiler keeps them out of client bundles). In data mode (Vite SPA) keep the same `features/` tree and replace `routes/` with a `router.tsx` that lists route objects with `lazy`.

## 5. Expo Router (React Native)

```
src/
├── app/                        # routes only
│   ├── _layout.tsx             # providers + <Stack> with <Stack.Protected guard={…}>
│   ├── (auth)/sign-in.tsx
│   ├── (app)/
│   │   ├── _layout.tsx         # <Tabs>
│   │   ├── index.tsx           # export { HomeScreen as default } from '@/features/home'
│   │   └── orders/[id].tsx
│   └── +not-found.tsx
├── features/<feature>/{screens,components,hooks,api,model,index.ts}
└── shared/{ui,lib,hooks,theme}
modules/                        # local Expo modules (created by npx create-expo-module --local)
app.config.ts  eas.json
```

Expo Router supports a top-level `src/app` directory. Every file under `app/` becomes a route, so components, hooks and helpers never live there.

## 6. Monorepo (pnpm workspaces + Turborepo or Nx)

```
apps/
├── web/                        # Next.js or React Router
├── mobile/                     # Expo
└── docs/                       # Storybook
packages/
├── core/                       # domain logic, API client, Zod schemas, query key factories — no react-native, no react-dom
├── ui/                         # web design system (built with tsup/tsdown, versioned)
├── ui-native/                  # mobile design system
├── config-eslint/  tsconfig/
pnpm-workspace.yaml  turbo.json
```

- Share logic (`core`), tokens and types across web and mobile; do not share screens. `packages/core` forbids `react-native` and `react-dom` imports by lint rule.
- One version of `react` across the workspace (pnpm `catalog:` or `overrides`); duplicate React copies break hooks.
- Expo SDK 54+ works with pnpm's default isolated installs; only fall back to `nodeLinker: hoisted` in `pnpm-workspace.yaml` when a specific native library fails to resolve. https://docs.expo.dev/guides/monorepos/
- Module Federation or separate deploys per team only when independent release cadence is a hard requirement.

## 7. Enforcing the boundaries

Core ESLint is enough for the two rules that matter; `eslint-plugin-boundaries` (https://github.com/javierbrea/eslint-plugin-boundaries) is the richer option when you need element types and per-layer policies.

```js
// eslint.config.js
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';

export default defineConfig(
  tseslint.configs.recommended,
  {
    files: ['src/shared/**/*.{ts,tsx}', 'src/entities/**/*.{ts,tsx}'],
    rules: {
      'no-restricted-imports': ['error', {
        patterns: [{ group: ['@/features/*', '@/app/*'], message: 'shared/ and entities/ must not import from features/ or app/.' }],
      }],
    },
  },
  {
    files: ['src/features/**/*.{ts,tsx}', 'src/app/**/*.{ts,tsx}'],
    rules: {
      'no-restricted-imports': ['error', {
        patterns: [{ group: ['@/features/*/*'], message: 'Import a feature through its index.ts (use relative imports inside the feature).' }],
      }],
    },
  },
);
```

Add `import/no-cycle` (from `eslint-plugin-import`) or `madge --circular src` in CI to catch circular feature imports.

## 8. Migrating a type-first tree (`components/`, `hooks/`, `utils/`)

1. List the product areas (routes are a good proxy); create one `features/<area>/` per area with an empty `index.ts`.
2. Move leaf components and their hooks first; leave re-exports in the old location so the diff stays reviewable.
3. Anything used by three or more features and free of business meaning goes to `shared/`; shared domain types go to `entities/`.
4. Turn on the lint rules in warn mode, fix, then switch to error and delete the re-exports.
5. Record the convention in `ARCHITECTURE.md`.
