Next.js App Router Architecture
Architecture Overview
All code lives under src/. Four top-level directories sit next to /app:
| Directory |
Purpose |
core/ |
Shared application logic — constants, hooks, providers, stores, types, utils |
lib/ |
External integrations — API client (Axios), auth, db, email |
components/ |
Global UI — ui/ (shadcn/design system), custom/ (reusable composites) |
app/ |
Routes and feature folders (co-located) |
Tech Stack
| Concern |
Library |
| Local state |
Zustand |
| Async state |
TanStack Query + Axios |
| Forms |
react-hook-form + Zod |
| Search params |
nuqs |
| UI |
shadcn / Radix |
| Translations |
Tolgee |
Feature Scaffolding Checklist
Every route-level feature lives inside its app/ segment and follows this structure:
app/(dashboard)/projects/
├── params.ts # nuqs search param definitions
├── prefetch.ts # server-side QueryClient + prefetch
├── page.tsx # server component (entry point)
├── fallback.tsx # loading skeleton for Suspense
├── _hooks/
│ ├── use-projects-params.ts # useQueryStates wrapper
│ └── use-projects.ts # query + mutation hooks
├── _validations/
│ └── project-schemas.ts # Zod schemas for forms
├── _components/
│ ├── projects-view.tsx # main client container
│ ├── project-card.tsx # presentational
│ └── project-form.tsx # form with react-hook-form
└── _sections/ # optional — for section-based pages
├── hero.tsx
└── features.tsx
Creation Workflow
- Define search params in
params.ts
- Create Zod schemas in
_validations/
- Write query/mutation hooks in
_hooks/
- Build
_components/ — container first, then presenters
- Create
prefetch.ts for server-side data loading
- Create
fallback.tsx skeleton
- Wire everything in
page.tsx with Suspense + HydrationBoundary
Core Patterns Quick Reference
Query hook:
export const projectsQueryOptions = (params: ProjectParams) => ({
queryKey: ["projects", params],
queryFn: () => api.get("/projects", { params }).then((res) => res.data),
});
export const useProjects = () => {
const [params] = useProjectsParams();
return useSuspenseQuery(projectsQueryOptions(params));
};
Search params:
export const projectsParams = {
search: parseAsString.withDefault("").withOptions({ clearOnDefault: true }),
page: parseAsInteger.withDefault(1).withOptions({ clearOnDefault: true }),
};
export const useProjectsParams = () => useQueryStates(projectsParams);
Zustand store:
export const useProjectStore = create<ProjectStore>()((set) => ({
selectedId: null,
setSelectedId: (id) => set({ selectedId: id }),
}));
Page pattern:
export default async function ProjectsPage({ searchParams }: PageProps) {
const params = await loadProjectsParams(searchParams);
const dehydratedState = await prefetchProjects(params);
return (
<HydrationBoundary state={dehydratedState}>
<Suspense fallback={<ProjectsFallback />}>
<ProjectsView />
</Suspense>
</HydrationBoundary>
);
}
Key Rules
- Underscore prefixes —
_components/, _hooks/, _validations/, _sections/ prevent Next.js route resolution
_sections/ — Optional folder for large pages (landing, marketing); sections are server components by default
- Co-location — Feature code lives with its route; shared code goes in
core/
- Naming — Feature-prefix all files:
project-card.tsx, use-projects.ts
- One hook file — Put all query + mutation hooks for a feature in a single file
useSuspenseQuery — Always use for SSR-hydrated queries (not useQuery)
- Barrel exports — Use
index.ts in core/ subdirectories (e.g., core/constants/index.ts)
- No fetch — Use the Axios api instance from
lib/ for all HTTP calls
- Providers — Compose into
root-provider.tsx, import in root layout.tsx
References
- Folder Structure — Full directory breakdown and placement rules
- Feature Scaffolding — Complete feature template with file contents
- Async State — Axios setup, queries, mutations, hydration
- Forms & Params — react-hook-form, Zod, nuqs patterns
- Components & State — Component structure, Zustand, providers
- shadcn/ui — Component installation, configuration, RTL support
- Metadata & SEO — generateMetadata, OG images, title templates
- Page Patterns — Server components, prefetch, Suspense, layouts
- Translations — Tolgee i18n, server/client translations, language switching
1---2name: nextjs-patterns3description: >4 Guide for building Next.js applications following a specific architecture5 with App Router, Zustand, TanStack Query, Axios, nuqs, react-hook-form,6 and Zod. Use when scaffolding features, creating components, setting up7 state management, building forms, or working with search params in8 Next.js projects.9metadata:10 source: https://skillmd.com/skills/majidraimi/nextjs-patterns11---1213# Next.js App Router Architecture1415## Architecture Overview1617All code lives under `src/`. Four top-level directories sit next to `/app`:1819| Directory | Purpose |20|-----------|---------|21| `core/` | Shared application logic — constants, hooks, providers, stores, types, utils |22| `lib/` | External integrations — API client (Axios), auth, db, email |23| `components/` | Global UI — `ui/` (shadcn/design system), `custom/` (reusable composites) |24| `app/` | Routes and feature folders (co-located) |2526### Tech Stack2728| Concern | Library |29|---------|---------|30| Local state | Zustand |31| Async state | TanStack Query + Axios |32| Forms | react-hook-form + Zod |33| Search params | nuqs |34| UI | shadcn / Radix |35| Translations | Tolgee |3637## Feature Scaffolding Checklist3839Every route-level feature lives inside its `app/` segment and follows this structure:4041```42app/(dashboard)/projects/43├── params.ts # nuqs search param definitions44├── prefetch.ts # server-side QueryClient + prefetch45├── page.tsx # server component (entry point)46├── fallback.tsx # loading skeleton for Suspense47├── _hooks/48│ ├── use-projects-params.ts # useQueryStates wrapper49│ └── use-projects.ts # query + mutation hooks50├── _validations/51│ └── project-schemas.ts # Zod schemas for forms52├── _components/53│ ├── projects-view.tsx # main client container54│ ├── project-card.tsx # presentational55│ └── project-form.tsx # form with react-hook-form56└── _sections/ # optional — for section-based pages57 ├── hero.tsx58 └── features.tsx59```6061### Creation Workflow62631. Define search params in `params.ts`642. Create Zod schemas in `_validations/`653. Write query/mutation hooks in `_hooks/`664. Build `_components/` — container first, then presenters675. Create `prefetch.ts` for server-side data loading686. Create `fallback.tsx` skeleton697. Wire everything in `page.tsx` with Suspense + HydrationBoundary7071## Core Patterns Quick Reference7273**Query hook:**74```ts75export const projectsQueryOptions = (params: ProjectParams) => ({76 queryKey: ["projects", params],77 queryFn: () => api.get("/projects", { params }).then((res) => res.data),78});7980export const useProjects = () => {81 const [params] = useProjectsParams();82 return useSuspenseQuery(projectsQueryOptions(params));83};84```8586**Search params:**87```ts88export const projectsParams = {89 search: parseAsString.withDefault("").withOptions({ clearOnDefault: true }),90 page: parseAsInteger.withDefault(1).withOptions({ clearOnDefault: true }),91};9293export const useProjectsParams = () => useQueryStates(projectsParams);94```9596**Zustand store:**97```ts98export const useProjectStore = create<ProjectStore>()((set) => ({99 selectedId: null,100 setSelectedId: (id) => set({ selectedId: id }),101}));102```103104**Page pattern:**105```tsx106export default async function ProjectsPage({ searchParams }: PageProps) {107 const params = await loadProjectsParams(searchParams);108 const dehydratedState = await prefetchProjects(params);109 return (110 <HydrationBoundary state={dehydratedState}>111 <Suspense fallback={<ProjectsFallback />}>112 <ProjectsView />113 </Suspense>114 </HydrationBoundary>115 );116}117```118119## Key Rules120121- **Underscore prefixes** — `_components/`, `_hooks/`, `_validations/`, `_sections/` prevent Next.js route resolution122- **`_sections/`** — Optional folder for large pages (landing, marketing); sections are server components by default123- **Co-location** — Feature code lives with its route; shared code goes in `core/`124- **Naming** — Feature-prefix all files: `project-card.tsx`, `use-projects.ts`125- **One hook file** — Put all query + mutation hooks for a feature in a single file126- **`useSuspenseQuery`** — Always use for SSR-hydrated queries (not `useQuery`)127- **Barrel exports** — Use `index.ts` in `core/` subdirectories (e.g., `core/constants/index.ts`)128- **No fetch** — Use the Axios api instance from `lib/` for all HTTP calls129- **Providers** — Compose into `root-provider.tsx`, import in root `layout.tsx`130131## References132133- [Folder Structure](references/folder-structure.md) — Full directory breakdown and placement rules134- [Feature Scaffolding](references/feature-scaffolding.md) — Complete feature template with file contents135- [Async State](references/async-state.md) — Axios setup, queries, mutations, hydration136- [Forms & Params](references/forms-and-params.md) — react-hook-form, Zod, nuqs patterns137- [Components & State](references/components-and-state.md) — Component structure, Zustand, providers138- [shadcn/ui](references/shadcn-ui.md) — Component installation, configuration, RTL support139- [Metadata & SEO](references/metadata-and-seo.md) — generateMetadata, OG images, title templates140- [Page Patterns](references/page-patterns.md) — Server components, prefetch, Suspense, layouts141- [Translations](references/translations.md) — Tolgee i18n, server/client translations, language switching