Structure A Frontend App

Structure a frontend app

Examples use React + Next.js (Pages Router) with a neutral listing domain; `/ are placeholders. Each rule: portable principle → **▸ Example (React/Next)** → **▸ Other stacks**. Backend equivalent: the structure-a-backend-service skill. General style & flow: code-conventions, git-flow`.

Core principle

The router layer stays thin — a route/page just renders a feature component. All app logic lives under src/, organized by feature. Shared cross-feature building blocks sit in typed top-level folders; everything single-feature lives inside that feature's module.

1. Repo layout

▸ Example (React/Next):

/
├── pages/                  # router (thin): pages → routes; _app, _document, api/ (Next-specific)
├── src/
│   ├── components/         # SHARED UI, type-based (Field/, Layout/, Shell/, ErrorBoundary/, Global*/)
│   ├── modules/            # FEATURE code, feature-based (modules///)
│   ├── hooks/              # general-purpose hooks (useInterval, useDebounced, SSR-safe helpers)
│   ├── helpers/hooks/      # domain hooks wrapping services/contexts (useMyProfile, useModalState)
│   ├── services/           # one HTTP client (BaseHttp) + one service class per entity
│   ├── queries/            # React Query: queries//.keys.ts + .queries.ts
│   ├── zustand-store/      # client/UI state, one store per feature
│   ├── contexts/           # cross-cutting React Context providers (auth, org, alert, locale)
│   ├── models/             # types: models/request/ + models/response/ (hand-authored DTOs)
│   ├── schemas/            # form validation schemas (*.schema.ts)
│   ├── utils/ constants/ enums/   # domain utils, constants, enums (incl. a Routes enum)
│   └── Config.ts           # typed config (public + private) — see write-frontend-code §7
├── styles/   locales/   public/   middleware.ts

▸ Other stacks: same src/ split with a different router folder (App Router app/, React-Router routes). The point: thin routes, feature modules, typed shared folders.

2. Routing (thin pages → feature modules)

• A page file is a thin wrapper that renders the feature component; no logic in the page.

▸ Example: pages/listings/index.tsx → `; real code in src/modules/listing/listing-list/`.

• RESTful route convention, centralized in an enum: / (list), //new

(create), //[id] (detail), //[id]/edit. Reference routes from the enum, never hard-code path strings.

• App-level providers nest once at the root (_app.tsx): session → query client → auth guard →

domain contexts → layout. (Next-specific; ▸ Other: a root `` tree.)

3. Feature module pattern

▸ Example — inside src/modules///:

listing-list/
├── ListingList.tsx          # presentational: renders UI using hooks from .actions
├── ListingList.actions.ts   # the logic: custom hooks (useListingList, useFetch…, handlers)
├── ListingCard.hook.ts       # computed props/callbacks for a sub-component (optional)
├── ListingList.module.scss   # component-scoped styles (optional)
└── index.ts                  # barrel: default export + re-export the .actions hooks

• Split logic from render. .actions.ts holds the hooks (state, data, side effects, handlers);

the .tsx consumes them and renders. Keeps components readable and logic testable. ▸ Other stacks: a useX hook module + a dumb component — same container/presentational split, any naming.

• Barrel index.ts per module so imports are one line:

import ListingList, { useListingList } from 'src/modules/listing/listing-list'.

4. Shared UI vs feature code

• src/components/ = shared, type-based (form Field/, Layout/, Shell/, ErrorBoundary/,

Global*). src/modules// = feature-based. Cross-feature → components/contexts/ services/utils; single-feature → its module.

• Design-system primitives come from a shared UI library (placeholder @org/web-ui), not rebuilt

per app — Button/Modal/Typography/Icon plus shared hooks/utils/theme. ▸ Other stacks: your component-library package.

5. Naming & imports

• Components/services/models: PascalCase (ListingCard.tsx; ListingService in

listing.service.ts; Listing.model.ts). Hooks: use* camelCase. Logic files: *.actions.ts, *.hook.ts. Styles: *.module.scss. Store: *.store.ts. Queries: *.keys.ts + *.queries.ts. Schemas: *.schema.ts. Folders kebab-case.

• Path aliases, never deep relative (src/*, @org/*): import x from 'src/modules/...', not ../../../.

6. Types: request vs response

Hand-authored DTOs split by direction: src/models/request/ (params/bodies) and src/models/response/ (API shapes), plus domain models. No code-gen. ▸ Other stacks: generated types or a shared schema — keep request and response shapes separate and typed.

Verification

• find src -maxdepth 1 -type d shows components, modules, hooks, services, queries, contexts,

models, schemas, utils; the router folder (pages/) is thin (pages just render feature components).

• Each feature lives under src/modules/// with .tsx + .actions.ts

(+ .module.scss) + index.ts; logic is in .actions.ts, not the .tsx.

• Imports use src/* / @org/* aliases (no ../../../); route paths come from the Routes enum.
• pnpm type-check + lint clean (lint = Biome here; general principles → code-conventions skill).

Related

• write-frontend-code — how to write the code inside these files.
• write-frontend-tests — Jest/RTL + Cypress/Cucumber.
• structure-a-backend-service — backend equivalent · code-conventions · git-flow.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kennguyen887
• Source: kennguyen887/agent-foundation
• License: MIT

Install and usage instructions live in the source repository linked above.