iru-setup-nextjs-web
Scaffold a new Next.js web application with `npx create-next-app@<latest>` driven entirely by explicit flags (TypeScript, App or Pages Router, ESLint, Tailwind or CSS Modules, `src/`, `@/*` alias, pac
SKILL.md.claude/skills/iru-setup-nextjs-web/SKILL.md
GitHubSetup Next.js Web
Scaffold a Next.js + TypeScript application with create-next-app, then layer on this catalog's standard
toolchain: Vitest + React Testing Library + jsdom (v8 coverage, 80% thresholds, lcov), ESLint flat config with
eslint-config-next + Prettier, next typegen && tsc --noEmit type checking, Playwright against the production
build, TypeDoc, a GitHub Pages–ready static export or a container-ready server build, and a sample feature that is
the living example of the iru-nextjs-code-one-task references. Every template below was generated and run in
throwaway scaffolds (create-next-app 16.4.0, Next.js 16.4.0, React 19.3, Node 24, npm 11, Vitest 5.0.4,
Playwright 1.63, TypeDoc 0.28) in five combinations — App Router server (previous caching model, with Docker),
App Router server with Cache Components, App Router static export, Pages Router server (with Docker), and Pages
Router static export. The gotchas called out inline are observed behavior.
The templates live in reference/ next to this file, each introduced by a File: \<path>` — when: <tags>` line
(write it only when every tag applies):
reference/config-templates.md—next.config.ts, Vitest, ESLint, Prettier, Playwright, TypeDoc, Sonar,Dockerfile,.dockerignore.reference/app-router-samples.md— the App Router sample feature, its unit tests, and its Playwright specs, plus the route table each variant must produce.reference/pages-router-samples.md— the same feature forrouter: pages.
Step 0 — Resolve inputs
This skill runs stand-alone (/iru-setup-nextjs-web) or driven by iru-setup-typescript-repository (flavor
nextjs), which resolves inputs once and passes them through args as key: value lines, e.g.:
app-name: bookshelf
description: A web catalogue of books.
license: Apache License 2.0
developer-name: Jane Doe
developer-email: jane@example.com
organization-url: https://github.com/jane
open-source: yes
sonar: cloud
sonar-organization: jane-github
sonar-project-key: jane_bookshelf
sonar-host-url: https://sonarcloud.io
output: server
e2e: playwright
distribution: internal
package-manager: npm
node-version: 24
visibility: public
ci: yes
accessibility: enforce
mode: new
Parse any such lines now; every key found is resolved and its question in Step 2 is skipped. If args is absent
or not in this format, treat everything as unset.
Recognized keys:
| Key | Values | Default when not asked |
|---|---|---|
app-name, description, license, developer-name, developer-email, organization-url |
free text | asked (Step 2) |
open-source |
yes/no |
asked |
sonar (+ sonar-organization, sonar-project-key, sonar-host-url) |
cloud/self-hosted/none |
asked |
router |
app/pages |
app |
output |
server/static |
asked |
cache-components |
yes/no |
no (asked only for router: app + output: server) |
styling |
tailwind/css-modules |
tailwind |
e2e |
playwright/none |
playwright |
distribution |
none/internal |
asked for output: server; always none for static |
docs-tool |
typedoc/none |
asked (TypeDoc recommended) |
agents-md |
yes/no |
yes |
package-manager |
npm/pnpm/yarn |
lockfile present, else npm |
node-version |
Node major | 24 (current LTS) — the Dockerfile's NODE_VERSION |
visibility |
public/private/internal |
resolved only if the Sonar question is asked |
ci |
yes/no |
yes (only consulted for the Sonar recommendation) |
accessibility |
enforce/report/off/none |
asked with e2e: playwright, else enforce — the UI tests' automated accessibility level written to .ui-quality.yml |
mode |
new/existing |
derived in Step 1 |
on-existing |
ask/keep/update/replace |
ask |
The orchestrator forwards router, cache-components, and styling only when they reached it through its own
args; their defaults above are therefore what most runs use, and Step 2 asks only cache-components (and only
when it matters). pages (GitHub Pages yes/no) is not a key of this skill: a static export is always built
Pages-ready (basePath from PAGES_BASE_PATH), and whether it gets deployed is the workflows skill's decision.
Contradictions are resolved, not obeyed, and reported in Step 10:
output: static+cache-components: yes→no: a static export has no server to stream dynamic holes, and every route must prerender as○/●.output: static+distribution: internal→none: there is no server to containerize; the export is the artifact.router: pages+cache-components: yes→no: Cache Components is an App Router feature.
mode: existing marks the run as an update, but never means "update silently": Step 1 still asks per artifact
unless on-existing says otherwise.
Accessibility level none and assistive-technology templates. accessibility takes enforce, report, off or
none (UI contract §8; the stand-alone question gains a fourth option, None — opt out entirely, e.g. a mandated
non-compliant design). With none: write accessibility: none to .ui-quality.yml, do not install or configure the
accessibility test tooling (axe-core in the Playwright tests and eslint-plugin-jsx-a11y), and omit the accessibility-specific attributes from the generated templates.
With enforce, report or off: include the assistive-technology attributes from the contract's §8 platform
subsections in every generated template — semantic landmarks, accessible names on icon-only buttons, alt on images (next/image), rem/relative font sizes, prefers-reduced-motion guards, visible focus — and, for enforce/report only, the automated checks. In
mode: existing, a prior .ui-quality.yml follows this skill's existing Update / Keep / Replace prompt and its
accessibility value is never silently flipped (Update sets it only when args supplied it).
Step 1 — Survey the repository
- If
modewasn't supplied, derive it:package.jsonwithnextindependenciesat the repository root ⇒existing, otherwisenew. Apackage.jsonwithoutnextis a different project — stop and ask whether to scaffold into a subdirectory instead. - Survey every artifact this skill owns:
package.json(the Next.js app itself —src/apporsrc/pages),next.config.*,vitest.config.*/vitest.setup.ts(or ajest.config.*— another runner),eslint.config.*(orbiome.json),.prettierrc*/.prettierignore,playwright.config.*+e2e/,typedoc.json,sonar-project.properties,Dockerfile/.dockerignore, the UI-contract files (.ui-quality.ymlat the repository root,e2e/support/ui-screenshots.ts,playwright/,e2e/components/), and the sample feature (src/lib/books.tsand its routes). - For an existing app, detect what it already is instead of asking: router (
src/app/app⇒app,src/pages/pagesonly ⇒pages),output('export'⇒static, elseserver),cacheComponents: true⇒cache-components: yes, styling (tailwindcssdependency ⇒tailwind),src/or root layout, import alias fromtsconfig.jsonpaths. Use those as resolved values and never change them as a side effect (Step 2 only confirms them in one line). An app withoutsrc/keeps its layout — adjust every template path (src/app/...→app/...) and the Vitestinclude/coverage globs accordingly. - Announce the mode before asking anything else:
- Nothing owned exists: "Scaffolding the Next.js app from scratch."
- Anything owned exists (or
mode: existing): "Updating an existing setup — found: <list with paths>." Then resolve one action per existing artifact:on-existingiskeep/update/replace: apply it to every artifact without asking (still print the list).- Otherwise: ask with
AskUserQuestion, up to 4 artifacts per call, naming any concrete contradiction with this run's choices (e.g. "next.config.tshas nooutput: 'export'but you choseoutput: static", "thelintscript still runsnext lint, which Next.js 16 removed", "asonar-project.propertiesexists but you chosesonar: none"):- Update (Recommended) — merge: add what's missing and correct outdated parts using the templates
(missing scripts/devDependencies, the coverage
include/excludeand thresholds, theserver-onlyandnext/navigationmocks,globalIgnores, the Chromium-only production-buildwebServer), keeping everything else. The user sees a diff; customizations survive, but a customized part this skill owns may be rewritten. - Keep as is — leave it untouched and skip the commands that only serve it. It may stay out of date or disagree with this run's choices — Step 10 lists each mismatch.
- Replace — regenerate from the template; customizations in it are lost (recoverable only from git). For
package.jsonthis means re-runningcreate-next-appover the app, which overwritessrc/app/layout.tsx,page.tsx,globals.css— say so and never recommend it. For ajest.config.*, Replace means switching to Vitest (Step 5); Keep stays on Jest and skips Step 5 (recommend Keep — the gate skills support both). - Stop (first batch only) — end without changing anything; report that and end here.
- Update (Recommended) — merge: add what's missing and correct outdated parts using the templates
(missing scripts/devDependencies, the coverage
- Defer the
sonar-project.propertiesquestion until Step 2 resolvessonar(withsonar: none, Update/Replace mean removing it), and theDockerfilequestion untildistributionis resolved. - The sample feature is only written on a scaffold-from-scratch run (or when the user explicitly asks for it on an update): never drop sample routes into an existing app's URL space.
- Placement (only when Step 3 will scaffold).
create-next-apprefuses a non-empty target directory unless every entry is on its own allow-list (verified in 16.4:.git,.gitignore,.gitattributes,.claude,.idea,.vscode,.zed,.cursor,.yarn,LICENSE,docs,mkdocs.yml,.npmignore,*.iml,.DS_Store,Thumbs.db, plus log files) — aREADME.md,CLAUDE.md,.github/, orCHANGELOG.mdmakes it print "The directory … contains files that could conflict" and exit.- Only allow-listed entries: scaffold into
.directly. If a.gitignoreexists, copy it aside first — the generated one replaces it — and merge the two afterwards (keep every existing line, append the template's missing ones). - Anything else present: ask with
AskUserQuestion— Scaffold into the repository root (Recommended for a repository that exists for this app) or Scaffold into a subdirectory named<app-name>. For the root, scaffold into a temporary directory (mktemp -d) with--skip-install, then move every generated entry into the root except ones that already exist there (merge.gitignoreas above; keep the existingREADME.md/CLAUDE.md—iru-setup-readmeowns the README; whenagents-md: yesand aCLAUDE.mdexists, append one@AGENTS.mdline to it instead of replacing it), delete the temporary directory, and run the package manager's install in the root.
- Only allow-listed entries: scaffold into
Step 2 — Collect identity and options
Use every value Step 0 or Step 1 already resolved; when an existing package.json supplies an identity value,
confirm it in one line instead of asking.
app-name — the
package.jsonname(lowercase, URL-safe; also the container image name the workflows skill derives). Default: the target directory's basename.app-title — not a key: the human-readable name used in metadata and TypeDoc (
<App title>in the templates). Derive it fromapp-name(bookshelf-web→ "Bookshelf Web") and confirm in one line.description, developer name, developer email, organization URL — for
package.json(description,author).license (
AskUserQuestion, same choices as every setup skill): Apache License 2.0 (recommended), MIT License, No license (proprietary), Other (ask its name). Remind in Step 10 to add aLICENSEfile if missing.open-source — Yes / No.
sonar — "Configure SonarCloud / SonarQube for this project?" Same rule as
iru-setup-react-web: resolvevisibilityonly now if missing (gh repo view --json visibility -q .visibility, lowercased; otherwise ask Public/Private;internalcounts as private; flag open source + private as contradictory). Recommendcloudonly for a public open-source repository (SonarCloud is free only for those), otherwisenonewithself-hostedas the second option; withci: norecommendnone(no CI would send reports) and, if Sonar is still chosen, say so in Step 10.cloudaskssonar-organization(suggest<owner>-githubfromgit remote get-url origin),sonar-project-key(suggest<owner>_<repo>), hosthttps://sonarcloud.io;self-hostedasks the host URL, the project key, and an organization only if that server uses them.output (
AskUserQuestion):- Server (Recommended unless the site is purely static content) —
next build+next start; Server Actions, Route Handlers, ISR, request-time rendering all available. - Static export —
output: 'export'toout/, hostable on GitHub Pages or any file host; no Server Actions, no request-time APIs, no dynamic Route Handlers, no proxy/middleware, no ISR, no image optimization — every route must prerender (○/●). The sample feature is adapted accordingly (Step 7).
- Server (Recommended unless the site is purely static content) —
cache-components (only
router: app+output: server;AskUserQuestion): No — previous model (Recommended: nothing is cached unless asked, route segment config works, every guide and library assumes it) or Yes — Cache Components ('use cache'+cacheLife/cacheTag, Partial Prerendering by default; every request-time read must sit under<Suspense>ornext buildfails). Name the consequence for later tasks:iru-nextjs-code-one-taskapplies the16-prevor16-ccprofile from this choice.distribution (only
output: server): None (the app is deployed by your own pipeline from the repository) or Internal (a container image pushed to GHCR by the release workflow — this step writesoutput: 'standalone', aDockerfile, a.dockerignore, and a health-check route). There is nostorevalue.docs-tool: TypeDoc (Recommended —
npm run docswritesdocs/api, which the workflows skill merges under the Antora site; also letsiru-typescript-tsdocverify instead of running audit-only) or None.accessibility (only with
e2e: playwright;AskUserQuestion): "Support accessibility and assistive technologies?" — Enforce (Recommended) (axe violations fail the UI tests) / Report only (listed, never failing) / Off (not run; the coding defaults still apply).
Do not ask router, styling, e2e, agents-md, or package-manager unless the user brings them up — their
defaults (app, tailwind, playwright, yes, detected/npm) are the house template.
Step 3 — Scaffold with create-next-app
Resolve the version live (npm view create-next-app version; it is released in lockstep with next) and pass
every choice as an explicit flag, including the negative ones:
npx --yes create-next-app@<version> <target> \
--ts --eslint --src-dir --import-alias "@/*" \
<--app | --no-app> \
<--tailwind | --no-tailwind> \
<--cache-components | --no-cache-components> \
--no-react-compiler \
<--agents-md | --no-agents-md> \
--no-agent-feedback \
<--use-npm | --use-pnpm | --use-yarn> \
--disable-git --yes [--skip-install]
| Choice | Flag |
|---|---|
router: app / pages |
--app / --no-app |
styling: tailwind / css-modules |
--tailwind / --no-tailwind (the starter then uses page.module.css) |
cache-components: yes / no |
--cache-components / --no-cache-components |
agents-md: yes / no |
--agents-md / --no-agents-md |
package-manager |
--use-npm / --use-pnpm / --use-yarn |
Why every flag is explicit (verified against create-next-app 16.4.0's own source and --help):
--yesfills every unprovided option from the user's saved preferences, else from built-in defaults — and the built-in default for Cache Components is ON (cacheComponents: truein its defaults object). A barecreate-next-app --yestherefore produces a Cache Components project. The CLI honors an explicit--no-<option>over both (it checksargvfor--no-cache-components,--no-tailwind,--no-app,--no-src-dir,--no-react-compiler,--no-agents-md,--no-eslint,--no-linter,--no-import-alias), so passing every flag makes saved preferences irrelevant.--yesis kept only so a flag added by a future release never blocks on a prompt.- Never pass
--reset-preferences: it deletes the user's saved preferences (a global file outside the repository) and then exits without scaffolding. --disable-git: the repository is the user's;create-next-appmust notgit initor commit.--no-agent-feedback: skips the opt-in feedback prompt added in 16.4.- Turbopack is the default bundler — don't pass
--webpack/--rspack.--turbopackis no longer in--help. --ts,--eslint,--src-dir,--import-alias "@/*"are house constants. Biome (--biome) is supported by the gate skills but not by this template.
Non-interactive as written (verified with stdin closed). What 16.4.0 generates for --app --tailwind --src-dir:
src/app/{layout.tsx,page.tsx,globals.css,favicon.ico}, public/*.svg, next.config.ts (with a turbopack.rules
block wiring @tailwindcss/turbopack for *.css — new in 16.4, replacing postcss.config.mjs),
eslint.config.mjs (flat config), tsconfig.json (strict, "@/*": ["./src/*"], includes .next/types),
AGENTS.md (no CLAUDE.md in 16.4, despite older docs), a .gitignore, and package.json with next/react
pinned exactly, eslint ^9, and @types/node ^20. --no-app writes src/pages/{_app,_document,index}.tsx,
src/pages/api/hello.ts, and src/styles/. It also runs next typegen after installing.
npm 11.19+ prints install-scripts … not yet covered by allowScripts: unrs-resolver during the install — that
package (an eslint-config-next dependency) ships a prebuilt binary and works without its postinstall; mention it,
don't act on it.
Step 4 — Identity, version, next.config.ts, starter cleanup
package.json: setname(Step 2),description,author("<name> <<email>> (<url>)"),license(SPDX id, or"UNLICENSED"for proprietary), andversion: "0.1.0-dev.0"— thex.y.z-dev.Ndevelopment versioniru-typescript-bump-versionand the workflows skill'ssync.ymlmaintain. Keep"private": true(an app is never published to npm).next.config.ts: write the variant fromreference/config-templates.mdfor the resolvedoutput/distribution, merging in every keycreate-next-appwrote — the Tailwindturbopack.rulesblock,cacheComponents: true+partialPrefetching: true(Cache Components), andreactStrictMode: true(Pages Router). Foroutput: staticthe template readsbasePathfromPAGES_BASE_PATH(empty when unset — the workflows skill's Pages deploy job sets it fromactions/configure-pages), setsimages: { unoptimized: true }andtrailingSlash: true, and exposes the base path asNEXT_PUBLIC_BASE_PATH. Verified: withPAGES_BASE_PATH=/my-repo npm run build,out/index.htmllinks/my-repo/books/and loads/my-repo/_next/static/....Root layout (
router: app): replace the starter'smetadataexport with site-wide defaults and give the layout one-line TSDoc (TypeDoc's strict run flags both otherwise); keep its fonts and classes as generated:/** Absolute origin used to resolve Open Graph and canonical URLs. */ const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000"; /** Site-wide metadata defaults; pages override `title` and `description`. */ export const metadata: Metadata = { metadataBase: new URL(siteUrl), title: { default: "<App title>", template: "%s | <App title>" }, description: "<description>", openGraph: { siteName: "<App title>", type: "website" }, };and prefix
export default function RootLayoutwith/** Root layout: the \<html>`/`<body>` shell around every page. */`.Starter cleanup (scaffold-from-scratch only): the starter
src/app/page.tsx(orsrc/pages/index.tsx) is replaced by the sample in Step 7; deletesrc/app/page.module.css(styling: css-modules),src/pages/api/hello.tsandsrc/styles/Home.module.css(Pages Router). Keeppublic/andglobals.css.Runtime dependencies for the sample (latest via
npm view <pkg> version; fallbacks verified 2026-10-13):router: app→server-only(0.0.1);router: app+output: server→ alsozod(4.6.7). The Pages Router samples need neither (server-onlybreaks modules shared withpages/).
Step 5 — Unit tests: Vitest + React Testing Library + jsdom
Dev dependencies — latest via npm view <pkg> version, fallbacks observed 2026-10-13:
| Package | Fallback | Note |
|---|---|---|
vitest, @vitest/coverage-v8 |
5.0.4 |
same version for both |
vite |
8.3.4 |
declared explicitly; otherwise only present as a peer of the plugin |
@vitejs/plugin-react |
6.1.2 |
|
jsdom |
30.1.2 |
|
@testing-library/react / dom / jest-dom / user-event |
16.3.3 / 10.4.2 / 7.0.1 / 14.6.8 |
|
@types/node |
^24 (the Node LTS major) |
required: see below |
Critical gotcha, verified: Vitest 5 declares peerDependencies["@types/node"]: "^22.0.0 || >=24.0.0", and
create-next-app scaffolds @types/node@^20 — installing Vitest 5 alone fails with npm ERESOLVE. Install
@types/node@^<node-version> (24 by default) in the same command as Vitest. Don't fall back to Vitest 4 to
dodge it.
npm install -D @types/node@^24 vitest@<v> @vitest/coverage-v8@<v> vite@<v> @vitejs/plugin-react@<v> jsdom@<v> \
@testing-library/react@<v> @testing-library/dom@<v> @testing-library/jest-dom@<v> @testing-library/user-event@<v>
Write vitest.config.mts and vitest.setup.ts from reference/config-templates.md. Notes that matter:
.mtskeeps the config ESM regardless ofpackage.json"type"(Next.js projects must not set"type": "commonjs").resolve: { tsconfigPaths: true }resolves@/*natively on Vite 8 — no plugin.include: ["src/**/*.test.{ts,tsx}"]keeps Playwright'se2e/*.spec.tsout of Vitest (Playwright'stest()fails inside Vitest).- The setup file mocks
server-only(the real module throws outside a React Server environment) and thenext/navigationclient hooks, keeping the realnotFound()/redirect()so tests can assert theirdigest. - Server-side tests (data layer, Server Actions, Route Handlers) start with
// @vitest-environment node.connection(),cookies(),headers(),revalidatePath()/updateTag()andcacheLife()/cacheTag()throw outside a request — verified:connectionwas called outside a request scope — so each test mocks exactly thenext/server/next/headers/next/cachefunctions its module imports. - Coverage:
include: ["src/**/*.{ts,tsx}"](so untested files show up at 0% instead of disappearing), excluding tests,*.d.ts, and the framework wiring jsdom can't render (src/app/layout.tsxwithnext/fontand<html>,src/pages/_app.tsx,src/pages/_document.tsx); reporterstext,lcov(coverage/lcov.infofor Sonar/CI) andjson-summary(coverage/coverage-summary.json, whichiru-typescript-coveragereads first); thresholds 80% for lines/branches/functions/statements sonpm run coverageitself fails below the gate.
Scripts: "test": "vitest run", "coverage": "vitest run --coverage".
Step 6 — Lint and format
next lint was removed in Next.js 16 and next build no longer lints: linting is the ESLint CLI over the flat
config. Keep the scaffold's eslint (^9; eslint-config-next 16.4 peers on eslint >=9) and
eslint-config-next (pinned to the next version), add Prettier and eslint-config-prettier
(fallbacks 3.9.10 / 10.1.8):
npm install -D prettier@<v> eslint-config-prettier@<v>
Write eslint.config.mjs, .prettierrc.json, and .prettierignore from reference/config-templates.md. The
ESLint config keeps eslint-config-next/core-web-vitals + /typescript and the scaffold's globalIgnores, adds
eslint-config-prettier/flat last, and ignores coverage/Playwright/TypeDoc output. .prettierignore lists
AGENTS.md/CLAUDE.md: next dev rewrites its agent-rules block there, so formatting it only produces churn.
Scripts: "lint": "eslint --max-warnings=0", "format": "prettier --write .", "format:check": "prettier --check .", "typecheck": "next typegen && tsc --noEmit".
typecheck must run next typegen first: App Router code uses the global PageProps/LayoutProps/RouteContext
helpers generated into .next/types, and a clean checkout fails tsc with TS2304: Cannot find name 'LayoutProps' without it. The scaffold's single tsconfig.json includes **/*.ts, **/*.tsx, **/*.mts, so
e2e/, playwright.config.ts, and vitest.config.mts are type-checked too — no project references needed
(unlike the Vite template).
Run npx prettier --write . once after Step 7 so the generated files match .prettierrc.json.
Step 7 — Sample feature and Playwright
Write the sample files from reference/app-router-samples.md (router: app) or
reference/pages-router-samples.md (router: pages) whose when: tags match the run. What the App Router sample
demonstrates, per variant:
| Piece | server |
static |
|---|---|---|
src/lib/books.ts |
server-only data layer returning DTOs; 16-cc: 'use cache' + cacheLife("hours") + cacheTag |
same (previous model), read at build time |
src/lib/session.ts |
auth stub (React.cache, demo user — replace before shipping) |
— |
src/app/books/actions.ts + add-book-form.tsx |
Server Action: authenticate → Zod safeParse → write → revalidatePath (prev) / updateTag (cc); useActionState form |
— (static export has no Server Actions) |
src/components/like-button.tsx |
Client Component leaf | same |
src/app/books/page.tsx, [id]/page.tsx |
async Server Components, metadata/generateMetadata, generateStaticParams, notFound() |
same, plus dynamicParams = false |
loading.tsx, error.tsx (retry prop, stable since 16.3), not-found.tsx |
yes | yes |
| Route Handlers | GET /api/books/[id] (RouteContext, 401/400/404) and GET /api/health (connection(), no-store) |
GET /books.json with dynamic = "force-static" |
Every source file has a colocated *.test.ts(x) exercising it — async Server Components are called as functions
and their result rendered, Server Actions are called with FormData including the anonymous and invalid cases,
Route Handlers are called with new Request(...) and a RouteContext. The suite reaches 100% lines and ≥94%
branches in every verified variant.
Playwright (e2e: playwright)
Add @playwright/test (latest; fallback 1.64.0) and, for output: static, serve (fallback 14.2.6) as dev
dependencies. Write playwright.config.ts and e2e/books.spec.ts from the templates. Don't run
npm init playwright — its template (three browsers, tests/ against an external site, no webServer) needs more
undoing than writing the file.
- The
webServerruns the production build on port 3100:npm run build && npm run start -- --port 3100forserver,npm run build && npm run start -- --listen 3100forstatic(where"start": "serve out").reuseExistingServer: !process.env.CI— underCIit never attaches to a dev server. output: server+distribution: internal:next startprints⚠ "next start" does not work with "output: standalone" configuration. Use "node .next/standalone/server.js" instead.— verified harmless (the server starts and every spec passes); the container runsnode server.jsitself.- Specs locate by role/name, never a bare
getByRole("alert")(Next injects a route announcer with that role). - Install the browser so the suite can run:
npx playwright install --with-deps chromium(on Linux without root,npx playwright install chromium). Each Playwright release pins its own Chromium build — a newer@playwright/testwith only an older browser cached fails withExecutable doesn't exist at …/chromium_headless_shell-<rev>; that is an environment gap to report, not a test failure.
Scripts: "test:e2e": "playwright test"; for output: static also "start": "serve out".
UI contract
The catalog's UI contract (repeated in iru-nextjs-code-one-task/reference/ui-contract.md) makes every component
and screen test capture its states into <repo root>/.ui-screenshots/<kind>/<Id>/<state>--<direction>--<theme>.png
and run axe at the level .ui-quality.yml sets. Write .ui-quality.yml at the repository root on every run
(also with e2e: none — the coding skills read it); an existing one follows Step 1's decision (Update sets only
accessibility when args supplied it and adds missing keys). With e2e: playwright, also write everything under
"UI contract" in reference/config-templates.md:
- dev dependencies
@axe-core/playwright(fallback4.14.0),vite(the major Vitest already uses), and@tailwindcss/viteforstyling: tailwind(@vitejs/plugin-reactis already there from Step 5); e2e/support/ui-screenshots.tsfrom this skill'sreference/ui-screenshots.ts;- the component gallery (
playwright/vite.config.ts,playwright/gallery/{index.html,main.tsx,next-stubs.tsx, next-image.tsx}) — Playwright's component testing is a plain project whosebaseURLis a gallery page driven by the built-inmount()fixture (@playwright/test≥ 1.62;@playwright/experimental-ct-reactis frozen), and Next.js has no Vite server to host it, so it gets its own on port 3200; only Client Components (and synchronous,server-only-free presentational components) can be storied; - the
componentsproject + gallerywebServerentry inplaywright.config.ts; src/components/like-button.story.tsx,e2e/components/like-button.spec.ts, ande2e/home.spec.ts(a screen capture of/, deterministic unlike the book list the Server Action spec mutates).
playwright/ is excluded from ESLint/Prettier (reference/config-templates.md's lint templates) and type-checked
by tsc --noEmit through the default **/*.tsx include (the gallery's /// <reference types="vite/client" />
covers import.meta.glob). The sample book list stays a small server-rendered list: it is bounded seed data, so the
contract's server pagination isn't needed there. Verified: CI=1 npm run test:e2e writes
component/LikeButton/default--{ltr,rtl}--{light,dark}.png and screen/Home/default--… with axe clean in both
themes.
Append Playwright's output to .gitignore if missing (/test-results/, /playwright-report/, /blob-report/,
/playwright/.cache/), .ui-screenshots/ (with the comment # UI test screenshots, regenerated on every UI test run), plus /docs/api/ (TypeDoc) and .integration-test.lock/ (the lock
iru-nextjs-code-one-task-group takes before next build/Playwright). iru-setup-typescript-gitignore maintains
the full file when the orchestrator runs it.
Step 8 — TypeDoc, Sonar, container image
docs-tool: typedoc: installtypedoc(fallback0.28.20), writetypedoc.json, add"docs": "next typegen && typedoc"(outputdocs/api, the path the workflows skill merges under the Antora site). Verified:npm run docsbuilds, and the gate's strict run (npx typedoc --emit none --treatWarningsAsErrors --validation.notDocumented true --disableGit --disableSources) exits 0 on every variant — the samples document every exported symbol, property, and union member for exactly that reason.sonar≠none: writesonar-project.propertiesfrom the template (placeholders from Step 2; tests are colocated, sosonar.tests=src+sonar.test.inclusions). Withsonar: nonewrite nothing and say so.distribution: internal(server only):output: 'standalone'is already innext.config.ts(Step 4); writeDockerfileand.dockerignorefrom the template withNODE_VERSION=node-version. Multi-stage (deps→builder→runneronnode:<node-version>-slim), the standalone server pluspublic/and.next/static, owned by and running as the image's non-rootnodeuser,HEALTHCHECKcalling/api/healthwith Node's built-infetch(nocurlin the slim image). The image name the release workflow pushes is thepackage.jsonnamewithout scope, lowercased — keepnamevalid for that.
Step 9 — Scripts and full verification
package.json scripts end up as (replace npm run with the chosen package manager's runner everywhere):
| Script | Command |
|---|---|
dev |
next dev (scaffold) |
build |
next build (scaffold) |
start |
next start (server) / serve out (static) |
lint |
eslint --max-warnings=0 |
format |
prettier --write . |
format:check |
prettier --check . |
typecheck |
next typegen && tsc --noEmit |
test |
vitest run |
coverage |
vitest run --coverage |
test:e2e |
playwright test (e2e: playwright) |
docs |
next typegen && typedoc (docs-tool: typedoc) |
These are the names iru-setup-typescript-github-workflows calls for the nextjs flavor and the gate skills
(iru-typescript-test with its e2e selector, iru-typescript-coverage, iru-typescript-code-quality,
iru-typescript-tsdoc) detect. Never rename them.
Run, in order, and fix anything red before reporting success:
npm run lint && npm run format:check && npm run typecheck && npm run test && npm run coverage && npm run build
Then:
- Route table: compare
next build's table with the variant's expected table in the samples reference (e.g.server+prev:○ /,○ /books,● /books/1,● /books/2,ƒ /api/books/[id],ƒ /api/health; Cache Components adds◐ /books/[id]and Revalidate1h/ Expire1dcolumns;static: only○/●). A mismatch is a finding, not something to paper over. e2e: playwright:CI=1 npm run test:e2e(itswebServerruns the production build itself).distribution: internal: ifdocker infosucceeds,docker build -t <app-name>:verify ., run it on a free port, wait fordocker inspect -f '{{.State.Health.Status}}'to reporthealthy,curl/api/healthand/books, confirmdocker exec <container> idis not root, then remove the container and image. Without a Docker daemon, report the image as unverified — never as built.docs-tool: typedoc:npm run docs.
Step 10 — Report
Start with the mode from Step 1 (scaffolded from scratch or updated an existing setup), then the app name,
location (root or subdirectory), license, create-next-app/next versions used, and per owned artifact the action
taken — created / updated / replaced / kept as is / removed — with every mismatch a kept artifact has with this
run's choices.
State the resolved options and where each came from (args, detected, asked, default): router, output,
cache-components (and therefore the coding profile 16-prev/16-cc later tasks will use), styling, e2e,
distribution, docs-tool, package-manager, node-version, open-source, sonar (+ visibility and its
source), and every contradiction Step 0 resolved (e.g. "cache-components: yes ignored: static export").
Report each verification command and its result: lint, format check, typecheck, unit tests (count), coverage
(lines/branches, coverage/lcov.info), build with the route table, Playwright (count, or why it couldn't run —
e.g. a missing browser build) with the screenshot count under .ui-screenshots/ and any accessibility violation
rule ids, TypeDoc, Docker build/health/non-root (or "unverified: no Docker daemon"). Also report .ui-quality.yml
with its action (created / updated / replaced / kept as is) and the accessibility level written.
Finish with Warn explicitly:
- Review every generated file before committing —
package.jsonauthor/description/license, metadata title/description, Sonar keys. src/lib/session.tsis a stub that treats every caller as signed in. Replace it with real authentication before deploying anything with Server Actions or authenticated Route Handlers; the actions and handlers already handle anullsession.- The in-memory book store resets on every server restart and is per-instance — it exists to prove the stack;
replace or delete the sample feature (
src/lib/books.ts,src/app/books/,src/app/api/books/,e2e/). output: static: the app is built for GitHub Pages withbasePathfromPAGES_BASE_PATH;next/imagesrcstrings and rawpublic/URLs needprocess.env.NEXT_PUBLIC_BASE_PATHprefixed manually. Server Actions, request-time APIs, middleware/proxy, and ISR will fail the build if added later.distribution: internal: multi-instance deployments need the sameNEXT_SERVER_ACTIONS_ENCRYPTION_KEYat build time on every instance; setNEXT_PUBLIC_SITE_URLat build time for correct Open Graph URLs.sonar: cloud/self-hosted: aSONAR_TOKENsecret and a matching project must exist before CI analysis works.- Playwright browsers were installed locally; CI needs
npx playwright install --with-deps chromium(the workflows skill's template does it). - If a license was chosen and no
LICENSEexists, suggestiru-check-license.
Verification notes
Exercised in $TMPDIR/iru-verify/ts-setup/nextjs/ on 2026-10-13 with create-next-app 16.4.0 / next 16.4.0 /
React 19.3.0, Node 24.20, npm 11.19, Vitest 5.0.4, @vitest/coverage-v8 5.0.4, Vite 8.3.4, jsdom 30.1.2, ESLint 9
eslint-config-next16.4.0, Prettier 3.9.10, TypeDoc 0.28.20, Zod 4.6.7, Docker 29.8:
| Variant | lint / format / typecheck / test / coverage / build | Playwright | Docker |
|---|---|---|---|
App, server, previous model, Tailwind, internal, TypeDoc, Sonar |
all pass; 25 tests, 100% lines / 94% branches; table as documented | 5/5 | built, healthy, runs as node (uid 1000), /books/999 → 404 |
| App, server, Cache Components, Tailwind | all pass; table shows ◐ /books/[id], 1h/1d |
5/5 (Server Action + updateTag read-your-own-writes) |
n/a |
| App, static export, CSS Modules, TypeDoc, Sonar | all pass; only ○/●; PAGES_BASE_PATH=/my-repo prefixes links and assets |
4/4 (serve out) |
n/a |
Pages, server, CSS Modules, internal |
all pass; ● /books with 1m revalidate |
3/3 (404 status asserted) | built, healthy |
| Pages, static export, Tailwind | all pass | 2/2 | n/a |
Playwright ran on 1.63.0 because only that release's Chromium build was cached locally (1.64.0 needs
chromium_headless_shell-1248, which was not downloaded); the configs and specs are version-independent. Not
verified: pnpm/yarn (scaffold flags and the Dockerfile variants), styling: css-modules with the Docker
image, create-next-app --biome, Next.js 15 or older (this skill always scaffolds the latest), and anything on a
Linux CI runner (the workflows skill covers that).