Setup Next.js Web

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Scaffold a Next.js + TypeScript web application with create-next-app, driven entirely by explicit flags so saved preferences can never leak in, then layer this catalog’s standard toolchain on top — Vitest with React Testing Library and jsdom, ESLint flat config with eslint-config-next, Prettier, next typegen && tsc --noEmit, Playwright against the production build, TypeDoc, optional Sonar, and either a GitHub Pages-ready static export or a container-ready server build — plus a tested sample feature. It also brings an existing Next.js app up to the same toolchain, announcing the mode and asking per artifact what to do with anything that already exists.

Purpose

iru-setup-nextjs-web gives a repository a Next.js app whose npm script names (lint, format, format:check, typecheck, test, coverage, test:e2e, build, start, docs) are exactly the ones Setup TypeScript GitHub Workflows calls for the nextjs flavor and the TypeScript gate skills detect. The sample feature (a server-only data layer, async Server Component pages, a Client Component leaf, a Server Action with Zod validation and an auth stub, Route Handlers, metadata, loading/error/not-found) is the living example of the iru-nextjs-code-one-task references, adapted to static export or the Pages Router where needed. Templates are kept in reference/ next to the skill (config-templates.md, app-router-samples.md, pages-router-samples.md) and were verified in five router/output combinations. The cache-components choice determines the 16-prev or 16-cc coding profile later tasks apply.

Following the catalog’s UI contract (see Building user interfaces) it also writes a root .ui-quality.yml (even with e2e: none, because the coding skills read it) (accessibility: none skips the axe tooling and the assistive-technology template attributes) and, with e2e: playwright, a Playwright component-testing project against a standalone Vite component gallery, the shared e2e/support/ui-screenshots.ts helper and axe-core checks, so the sample LikeButton and the Home screen are captured into .ui-screenshots/ across left-to-right/right-to-left × light/dark.

Purpose group

TypeScript/Node Bootstrap

Plugin

Shipped by the iru-nextjs plugin of the ai-catalog marketplace (install with /plugin install iru-nextjs@ai-catalog; see Plugins).

Invocation

/iru-setup-nextjs-web

Inputs

Everything is optional: the skill is invoked stand-alone, or driven by Setup TypeScript Repository, which passes resolved values through args as newline-separated key: value lines so the matching Step 2 questions are skipped.

Argument Required Description Default

app-name, description, license, developer-name, developer-email, organization-url

No

Identity values written to package.json (name, description, author, license).

Asked in Step 2

open-source

No

yes/no; drives the recommended sonar value.

Asked

sonar (+ sonar-organization, sonar-project-key, sonar-host-url)

No

cloud/self-hosted/none; gates sonar-project.properties.

Asked (cloud recommended only for public open source)

router

No

app or pages.

app

output

No

server (next build + next start) or static (output: 'export', Pages-ready via PAGES_BASE_PATH).

Asked

cache-components

No

yes/no; App Router + server output only.

no (asked only when it matters)

styling

No

tailwind or css-modules.

tailwind

e2e

No

playwright or none.

playwright

distribution

No

none or internal (GHCR container image: output: 'standalone', Dockerfile, health-check route).

Asked for server; always none for static

docs-tool

No

typedoc or none.

Asked (TypeDoc recommended)

agents-md

No

yes/no, passed to create-next-app as --agents-md/--no-agents-md.

yes

package-manager

No

npm, pnpm or yarn.

Lockfile present, else npm

node-version

No

Node major, used as the Dockerfile’s `NODE_VERSION.

24

accessibility

No

enforce, report, off or none (opt out entirely) — the UI tests' automated (axe) accessibility level, written to .ui-quality.yml.

Asked with e2e: playwright (Enforce recommended), else enforce

visibility, ci

No

Only used to key the Sonar recommendation (internal behaves like private; ci: no recommends none).

Resolved only if the Sonar question is asked; ci defaults to yes

mode

No

new or existing; existing never means silent update.

Derived in Step 1 (next in dependencies means existing)

on-existing

No

ask, keep, update or replace, answering Step 1’s per-artifact question at once.

ask

Contradictions are resolved rather than obeyed and reported: output: static forces cache-components: no and distribution: none, and router: pages forces cache-components: no.

Outputs

  • A Next.js app (src/app or src/pages) scaffolded by create-next-app with explicit flags, version 0.1.0-dev.0, "private": true, and a next.config.ts variant for the resolved output/distribution.

  • Vitest + React Testing Library + jsdom configuration (v8 coverage, 80% thresholds, lcov at coverage/lcov.info), ESLint flat config, Prettier config, and the shared npm scripts listed in Purpose.

  • The sample feature with colocated unit tests (scaffold-from-scratch runs only), plus playwright.config.ts and e2e/ specs when e2e: playwright.

  • .ui-quality.yml at the repository root (accessibility, directions, themes), always written. With e2e: playwright also the UI-contract files: e2e/support/ui-screenshots.ts, the component gallery under playwright/ (Vite config, next/link/next/navigation/next/image stand-ins), the components Playwright project with its gallery webServer, src/components/like-button.story.tsx, e2e/components/like-button.spec.ts and e2e/home.spec.ts, plus the @axe-core/playwright and vite dev dependencies. Their captures go to the gitignored .ui-screenshots/component/LikeButton/ and .ui-screenshots/screen/Home/.

  • typedoc.json when docs-tool: typedoc; sonar-project.properties when sonar is not none; Dockerfile and .dockerignore when distribution: internal.

  • .gitignore additions for Playwright, .ui-screenshots/, TypeDoc and the integration-test lock.

  • A final report with the mode, per-artifact action (created / updated / replaced / kept as is / removed), resolved options and their sources, every verification result (including the screenshot count under .ui-screenshots/ and any accessibility violation rule ids), the .ui-quality.yml action and accessibility level, and explicit warnings (auth stub, in-memory store, static-export limits, secrets).

Execution flow

flowchart TD A["Start /iru-setup-nextjs-web"] --> B["Step 0: parse args, resolve contradictions"] B --> C["Step 1: survey repository, detect router/output/styling"] C --> D{"package.json without next?"} D -- yes --> D1["Ask: scaffold into a subdirectory?"] D -- no --> E{"Owned artifacts exist?"} D1 --> E E -- no --> E1["Announce: from scratch"] E -- yes --> E2["Announce: updating existing setup"] E2 --> F{"on-existing set?"} F -- yes --> F1["Apply to every artifact"] F -- no --> F2{"Ask per artifact:\nUpdate / Keep / Replace / Stop"} F2 -- Stop --> Z["Report untouched; end"] F2 -- other --> G F1 --> G["Step 2: collect identity and options\n(incl. accessibility)"] E1 --> G G --> H["Step 3: npx create-next-app with explicit flags"] H --> I["Step 4: identity, version, next.config.ts, starter cleanup"] I --> J["Step 5: Vitest + React Testing Library"] J --> K["Step 6: ESLint and Prettier"] K --> L["Step 7: sample feature, Playwright\nand UI contract tests"] L --> M["Step 8: TypeDoc, Sonar, Dockerfile"] M --> N["Step 9: scripts and verification\nlint, format, typecheck, test, coverage, build"] N --> O["Route table, Playwright, Docker health, TypeDoc checks"] O --> P["Step 10: report mode, actions, warnings"]

Dependencies

Invokes

None — iru-setup-nextjs-web is a leaf skill; it does not call any other skill in this catalog. It runs npx create-next-app, the package manager, Playwright, TypeDoc and Docker directly. It mentions Setup Readme (owns the README), Setup TypeScript Gitignore (maintains the full .gitignore) and Check License only as follow-ups for the user or orchestrator.

Invoked by

Related agents

None — all commands run directly in the skill’s own context.

Source

SKILL.md on GitHub — the file this page was generated from.