structure-a-frontend-applisted

# Structure a frontend app Examples use React + Next.js (Pages Router) with a neutral `listing` domain; `<feature>`/`<Entity>` 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):** ``` <app>/ ├── 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/<feature>/<sub-feature>/) │ ├── 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/<domain>/<domain>.keys.ts + .queries.ts │ ├── zustand-store/ # client/UI state, one store per feature │ ├── contexts/ # cross-cutting React Context