nextjs-quality
Applies App-Router-era Next.js quality practice — where generic Node advice and
pages-router folklore actively mislead. The failures this skill fixes: models
sprinkle use client until errors stop, configure generic ESLint instead of the
Next ruleset, quote deprecated next lint-era workflows, and "optimize" bundles
without measuring.
When NOT to use
- Generic Node/TS lint outside a Next app →
node-lint.
- Unit/component test setup →
node-testing.
- Packaging a library →
node-packaging; deploys/hosting → out of scope.
- Writing app features → ordinary dev work.
Workflow
- Audit current state: Next major (the playbook version-gates what's
stable vs experimental per line),
next.config.*, lint setup, next build
output as the baseline.
- Lint the Next way:
eslint-config-next in flat config (the playbook has
the current wiring — verify the next lint deprecation state for the
installed major); its RSC/boundary rules are the point, don't swap them for
generic configs.
- next.config hardening from the playbook checklist:
reactStrictMode,
typed routes (status verified per version), images config, output mode
matched to the deploy target, source-map policy — each explicit, none by
default-trust.
- Boundary hygiene (the hydration /
use client complaint): find the
actual offending imports; make client islands minimal; keep data fetching
and secrets server-side (server-only where it protects); add the lint
rules that catch regressions. Playbook has the common-causes checklist.
- Bundle work is measurement work: analyzer first, then the real levers —
dynamic imports, server components for static parts, tree-shakeable imports,
next/image + next/font — and re-measure; report the delta, not vibes.
- Verify after every change:
next build green is the loop gate; type and
lint gates stay on.
Output spec
An explicit hardened next.config, Next-native lint in force, no unexplained
use client at module tops, measured bundle deltas for optimization asks, and
next build passing — with anything version-experimental labeled as such.
Gotchas
use client marks a boundary, not a fix — adding it at the top of a big tree
ships the tree to the client; islands, not blankets.- Hydration mismatches are usually non-deterministic render inputs (dates,
random, locale) — the checklist finds them faster than console archaeology.
output: 'export' silently disables server features — deploy target first,
config second.- Next majors move fast: the playbook version-gates typed-routes/lint specifics;
re-verify against nextjs.org docs for the installed major.
Files
references/nextjs-playbook.md — version-gated config checklist, flat-config
lint wiring, boundary/hydration checklists, bundle levers, env validation.
1---2name: nextjs-quality3description: Tunes Next.js App Router quality - next.config hardening, eslint-config-next flat config, React Strict Mode, typed routes, RSC and use-client boundary hygiene, measured bundle work, image/font optimization. Use when the user asks to production-harden a Next.js app, fix hydration or use-client errors, or shrink the bundle. Not for generic Node linting, tsconfig strictness, unit tests, or deploys.4license: MIT5---67# nextjs-quality89Applies App-Router-era Next.js quality practice — where generic Node advice and10pages-router folklore actively mislead. The failures this skill fixes: models11sprinkle `use client` until errors stop, configure generic ESLint instead of the12Next ruleset, quote deprecated `next lint`-era workflows, and "optimize" bundles13without measuring.1415## When NOT to use1617- Generic Node/TS lint outside a Next app → `node-lint`.18- Unit/component test setup → `node-testing`.19- Packaging a library → `node-packaging`; deploys/hosting → out of scope.20- Writing app features → ordinary dev work.2122## Workflow23241. **Audit current state**: Next major (the playbook version-gates what's25 stable vs experimental per line), `next.config.*`, lint setup, `next build`26 output as the baseline.272. **Lint the Next way**: `eslint-config-next` in flat config (the playbook has28 the current wiring — verify the `next lint` deprecation state for the29 installed major); its RSC/boundary rules are the point, don't swap them for30 generic configs.313. **next.config hardening** from the playbook checklist: `reactStrictMode`,32 typed routes (status verified per version), images config, `output` mode33 matched to the deploy target, source-map policy — each explicit, none by34 default-trust.354. **Boundary hygiene** (the hydration / `use client` complaint): find the36 actual offending imports; make client islands minimal; keep data fetching37 and secrets server-side (`server-only` where it protects); add the lint38 rules that catch regressions. Playbook has the common-causes checklist.395. **Bundle work is measurement work**: analyzer first, then the real levers —40 dynamic imports, server components for static parts, tree-shakeable imports,41 `next/image` + `next/font` — and re-measure; report the delta, not vibes.426. **Verify after every change**: `next build` green is the loop gate; type and43 lint gates stay on.4445## Output spec4647An explicit hardened `next.config`, Next-native lint in force, no unexplained48`use client` at module tops, measured bundle deltas for optimization asks, and49`next build` passing — with anything version-experimental labeled as such.5051## Gotchas5253- `use client` marks a boundary, not a fix — adding it at the top of a big tree54 ships the tree to the client; islands, not blankets.55- Hydration mismatches are usually non-deterministic render inputs (dates,56 random, locale) — the checklist finds them faster than console archaeology.57- `output: 'export'` silently disables server features — deploy target first,58 config second.59- Next majors move fast: the playbook version-gates typed-routes/lint specifics;60 re-verify against nextjs.org docs for the installed major.6162## Files6364- `references/nextjs-playbook.md` — version-gated config checklist, flat-config65 lint wiring, boundary/hydration checklists, bundle levers, env validation.
Paldom