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-architectureandreact-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 toshared/. - Tests sit next to the file (
OrderRow.test.tsx); test helpers insrc/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/coreforbidsreact-nativeandreact-domimports by lint rule. - One version of
reactacross the workspace (pnpmcatalog:oroverrides); duplicate React copies break hooks. - Expo SDK 54+ works with pnpm's default isolated installs; only fall back to
nodeLinker: hoistedinpnpm-workspace.yamlwhen 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.
// 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/)
- List the product areas (routes are a good proxy); create one
features/<area>/per area with an emptyindex.ts. - Move leaf components and their hooks first; leave re-exports in the old location so the diff stays reviewable.
- Anything used by three or more features and free of business meaning goes to
shared/; shared domain types go toentities/. - Turn on the lint rules in warn mode, fix, then switch to error and delete the re-exports.
- Record the convention in
ARCHITECTURE.md.