Org Skills

Feature-first layouts — web, mobile and monorepo

Supporting material for react-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

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.

// 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.