The Next.js dashboard: how the app is scaffolded, and the honest-coverage UI as
it gets built. Teaching why, newest topics appended as they come up.
Stack as scaffolded (2026-07-31): Next.js 16.2.12 (App Router) · React 19.2.4 ·
TypeScript 5 · Tailwind CSS v4, code under src/.
1. Scaffolding the app — create-next-app
We generated the app with:
npx create-next-app@latest . --ts --app --tailwind --eslint \
--src-dir --turbopack --import-alias "@/*" --use-npm --disable-git --agents-mdTwo choices worth remembering:
- Every option passed as a flag → zero prompts.
create-next-appis
interactive by default. Specifying--ts --app --tailwind …for every
question it would ask makes the run fully non-interactive and reproducible —
the command itself documents exactly what was chosen. --disable-git— the generator normally runsgit initand makes a first
commit. We disable that because git is owned by hand on this project; the
scaffold should produce files, not history.--src-dirputs app code undersrc/, keeping the repo root for config,
docs/, and (later)supabase/.
@/* import alias
--import-alias "@/*" wires a path alias in tsconfig.json:
"paths": { "@/*": ["./src/*"] }So import { db } from "@/lib/db" resolves to src/lib/db from anywhere, with
no ../../../ climbing. moduleResolution: "bundler" (also in the generated
tsconfig) is the modern setting that lets TS resolve imports the way bundlers
actually do.
2. “This is NOT the Next.js you know” — read the bundled docs first
--agents-md generated an AGENTS.md at the repo root (and a one-line
CLAUDE.md that just does @AGENTS.md to include it). Its whole content is a
warning:
This version has breaking changes — APIs, conventions, and file structure may
all differ from your training data. Read the relevant guide in
node_modules/next/dist/docs/before writing any code.
That folder really exists and is the version-exact documentation for the
Next.js actually installed:
node_modules/next/dist/docs/
01-app/ 02-pages/ 03-architecture/ 04-community/ index.md
Why this matters: Next.js ships breaking changes often (e.g. the App Router
itself, the proxy.ts rename in 16). Reading 01-app/ from the installed copy
beats reading a blog post or trusting memory — it can’t be stale, because it’s
literally the code you’re running. This is the same “verify against primary
sources” habit, made trivially local.
3. Tailwind v4 is CSS-first — there is no tailwind.config.js
Tailwind v3 configured everything in a JS file (tailwind.config.js with a
content array, theme.extend, etc.). v4 moved configuration into CSS. The
generated setup is:
postcss.config.mjs — Tailwind runs as a PostCSS plugin:
const config = { plugins: { "@tailwindcss/postcss": {} } };
export default config;src/app/globals.css — one import pulls in all of Tailwind, and a @theme
block is the config:
@import "tailwindcss";
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--font-sans: var(--font-geist-sans);
}@import "tailwindcss";replaces the old@tailwind base; @tailwind components; @tailwind utilities;trio.@themedefines design tokens as CSS custom properties, and Tailwind
generates matching utilities from them — e.g.--color-backgroundmakes
bg-backgroundreal. So theme customisation happens in CSS next to the tokens,
not in a separate JS file.- Content detection (which files to scan for class names) is now automatic in
v4 — nocontent: [...]array to maintain.
Practical upshot for our dashboard: to add a colour for, say, the “flagged”
light, we’ll define --color-flagged in @theme and then use bg-flagged
directly, rather than editing a JS config.
See also
shell.md— the move-aside trick used to scaffold into the non-empty repo- app repo
~/code/spectroniq/sorepoint/DECISIONS.md— why Next + Supabase, worker-not-route
Software engineering
Infrastructure & security
Computer science
Hardware & engineering