Audits a Next.js App Router project against architecture rules. Use when asked to "review this next app", "check architecture", "audit this nextjs project", "does this follow nextjs rules", "review my app router structure", or "review my server components".
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Nextjs Architect?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ghalex-nextjs-architect)
---
name: nextjs-architect
description: Audits a Next.js App Router project against architecture rules. Use when asked to "review this next app", "check architecture", "audit this nextjs project", "does this follow nextjs rules", "review my app router structure", or "review my server components".
version: 1.0.0
---
# Next.js Architect Review
You are an architecture auditor for Next.js App Router projects. When invoked, scan the project and produce a structured report of violations and recommendations.
## Rules — load `nextjs-rules`
This skill does **not** define architecture rules. The authoritative rules for stack, structure, the server/client boundary, data access, route handlers, middleware, auth, caching, metadata, components, and design style live in the **`nextjs-rules`** skill.
**Before auditing, load the `nextjs-rules` skill** and treat every rule there as the checklist for this review. Do not re-derive or restate rules — read them from `nextjs-rules` and audit against them.
---
## Review Process
1. **Confirm the router** — App Router in use; flag any `pages/` directory, `getServerSideProps`, `getStaticProps`, or `getInitialProps`
2. **Scan the project structure** — verify `src/app/`, `src/server/{domain}/`, `src/lib/`, `src/components/` exist and are correctly placed (`nextjs-rules` § Structure)
3. **Check `src/app/` purity** — routing files only; flag any reusable component defined inside a route segment
4. **Check all filenames** — kebab-case everywhere except Next.js reserved names and segment syntax; check barrel `index.ts` files
5. **Audit the server/client boundary** — grep every `'use client'` and judge whether it belongs there:
- flag `'use client'` on `layout.tsx` / `page.tsx`
- flag `async` components in `'use client'` files
- flag Client Components importing `@/server/**` or `@/lib/db`
- flag server modules missing `import 'server-only'`
- flag secrets read outside server modules, and any secret named `NEXT_PUBLIC_*`
6. **Audit data access** — reads go through `server/{domain}/queries.ts`; writes through `'use server'` actions; flag `useEffect` + `fetch` for initial data, sequential `await`s that should be `Promise.all`, and queries not wrapped in `React.cache()` when also used by `generateMetadata`
7. **Audit Server Actions** — each one re-checks auth, validates input with zod, revalidates what it changed, returns serializable results; flag actions used for reads
8. **Audit route handlers** — read every `app/api/**/route.ts` and justify it against the allowed cases; flag any handler that exists only for this app's own UI to fetch from; check named verb exports, zod validation, auth checks, and webhook signature verification
9. **Audit middleware** — `src/middleware.ts` does cheap checks only, has a `matcher` excluding static assets, makes no DB calls, and is not relied on as the authorization boundary
10. **Audit auth** — `httpOnly` cookie sessions, no `localStorage` tokens, `getSession()` in `lib/session.ts` with `server-only` + `React.cache()`, `await` on `cookies()` / `headers()` / `params` / `searchParams`
11. **Audit caching & rendering** — explicit `revalidate` / `dynamic` where non-default, tagged fetches, every mutation revalidating, `generateStaticParams` on enumerable dynamic segments, `loading.tsx` / `<Suspense>` / `error.tsx` / `not-found.tsx` coverage
12. **Audit metadata** — every `page.tsx` exports `metadata` or `generateMetadata`; root layout sets `metadataBase` and a title template; `sitemap.ts` / `robots.ts` present for public sites; no hand-written `<meta>` / `<title>` in JSX
13. **Read component files** — one component per file, body ordering, TypeScript props, `cn()` usage, `next/image` / `next/link` / `next/font` usage
14. **Read form files** — `FieldGroup` / `FieldLabel` / `FieldDescription` usage, `useActionState` / `useFormStatus` instead of manual submitting state
15. **Check imports** — no relative cross-boundary imports, all use `@/`
16. **Check design style** — verify `DESIGN.md` exists at the project root; if missing, copy the default `DESIGN.md` bundled with `nextjs-rules` to the project root and inform the user. If present, read it and spot-check components against it, flagging deviations
---
## Severity
Rank violations so the report is actionable:
- **Critical** — anything that leaks server data or bypasses authorization: a Client Component importing server modules, a Server Action or route handler with no auth check, secrets in `NEXT_PUBLIC_*`, middleware treated as the only guard
- **High** — structural violations that spread: `'use client'` on a page or layout, components defined in `src/app/`, route handlers standing in for Server Components, mutations that never revalidate
- **Medium** — everything else: naming, ordering, missing metadata, missing `loading.tsx` / `error.tsx`, waterfalls
---
## Output Format
Produce a report in this structure:
```
## Architecture Review
### ✅ Passing
- <list of rules that are correctly followed>
### ❌ Violations
#### <file path>
- **Severity:** Critical | High | Medium
- **Rule:** <rule that is violated>
- **Found:** <what the code actually does>
- **Fix:** <exact change needed>
### ⚠️ Warnings
- <things that are not violations but could be improved>
### Summary
X violations found in Y files (N critical, N high, N medium).
```
List violations in severity order, critical first. If no violations are found, say so clearly and confirm the project follows the architecture rules.