projx / nextjs

# nextjs — React / Next.js frontend (projx template)

> Stack-scoped notes. The root [`../CLAUDE.md`](../CLAUDE.md) carries cross-cutting standards — read both, they compose.
>
> This directory is a **projx template**: a working SPA-style app whose own suite must stay green on the projx repo (root §"Per-template gates") **and** the source the CLI copies into scaffolded projects. It mirrors `vitejs/` feature-for-feature but idiomatic to the App Router; `vitejs` remains the default frontend.

## Stack

- **Framework** — React 19 + Next.js (App Router), TypeScript strict
- **Build** — `next build` with `output: 'standalone'` (containerized `node server.js`)
- **Auth** — OIDC token flow (`src/lib/auth.ts`); request-path-only refresh with one shared in-flight lock (no timer)
- **Config** — DB-backed runtime config via server-injected `window.__RUNTIME_CONFIG__` (`src/lib/runtime-config*.ts`); env bootstrap-only, no `NODE_ENV` branching
- **Errors** — `ErrorScaffold` wired into route-level `error.tsx` / `global-error.tsx` / `not-found.tsx`; API client parses `{detail, request_id}`
- **Monitoring** — `@sentry/nextjs` (DSN-from-env gated), `instrumentation*.ts` + `sentry.*.config.ts`
- **Styling** — Tailwind CSS v4 via `@tailwindcss/postcss` (`postcss.config.mjs`); design tokens live in the `@theme` block of `src/app/globals.css`, dark theme overrides the same custom properties under `[data-theme='dark']`
- **Test** — Vitest + v8 coverage; E2E coverage via SWC instrument (`NEXT_COVERAGE`)

## Layout

| Path                | What it holds                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `src/app/`          | App Router: `layout.tsx`, `page.tsx`, `login/`, `error.tsx`, `global-error.tsx`, `not-found.tsx`, `globals.css`             |
| `src/middleware.ts` | Edge auth gating                                                                                                            |
| `src/lib/`          | `api.ts`, `auth.ts`, `runtime-config.ts`, `runtime-config-script.ts`, `sentry.ts`, `types.ts`                               |
| `src/components/`   | `AuthProvider`, `Providers`, `ThemeProvider`, `Layout`, `Toast`, `ConfirmDialog`, `ErrorScaffold`, `Dashboard`, `LoginForm` |
| `tests/`            | Vitest suites (mirror `src/`, never co-located under `src/`)                                                                |
| `next.config.ts`    | `output: 'standalone'`, security headers via `headers()`                                                                    |
| `Dockerfile.ejs`    | Multi-stage standalone build                                                                                                |

## Quality gates (root §"Per-template gates")

`pnpm format:check` (prettier) → `pnpm lint` (eslint flat config) → `pnpm typecheck` (`tsc --noEmit`) → `pnpm build` (`next build`) → `pnpm test` (vitest, v8 ≥80%). Locally `bash ../scripts/ci-local.sh nextjs`.

## Things that bite

- **Tests live in `tests/`, not co-located under `src/`** — same rule as the other JS templates.
- **`NEXT_PUBLIC_` vars** are the only env exposed to the client; runtime config is server-injected, not build-time inlined — don't reach for `process.env` in client components.
- **OIDC env required at runtime**: the auth module fails loud without its OIDC config — CI/tests provide it (see the vitejs `VITE_OIDC_*` precedent; nextjs uses `NEXT_PUBLIC_OIDC_*`).
- **Standalone Docker** serves `node server.js` on port 3000 — no nginx/certbot (unlike `vitejs`).
- **pnpm 11 config lives in `pnpm-workspace.yaml`** — the `postcss` override and `allowBuilds` (`sharp`/`@sentry/cli` disabled; they ship prebuilt binaries) go there, **not** the package.json `pnpm` field. Adding a native dep with a build script means adding it to `allowBuilds` or pnpm 11 blocks it.
- **The `brace-expansion` override is scoped to the 5.x line** (`>=5.0.0 <5.0.8` → `>=5.0.8 <6`), never a blanket `<5.0.8` — a blanket bound forces `minimatch@9` (via `@vitest/coverage-v8`) off its native `brace-expansion@2.x` onto `5.x`, whose CJS export shape crashes coverage (`brace_expansion_1.default is not a function`). Same constraint as `fastify`.
- **`@theme` vs `:root` in `globals.css`** — a token goes in `@theme` when Tailwind should generate a utility from it (`--color-*`, `--spacing-*`, `--text-*`, `--radius-*`, `--shadow-*`, `--font-*`, `--font-weight-*`, `--leading-*`). Tokens only ever read by CSS (`--z-*`, `--sidebar-w`, `--transition-*`, `--ring-*`, `--border-width`) stay in `:root` — putting them in `@theme` generates nothing and implies a utility axis that doesn't exist.
- **Never `@theme inline`** — inline mode bakes the value into each utility, which silently breaks the `[data-theme='dark']` override model. Plain `@theme` emits `var()` references, so flipping a custom property reskins every utility. For the same reason there is no `dark:` variant anywhere in this template.
- **Tailwind namespaces are load-bearing** — font _weights_ must be `--font-weight-*`, not `--font-*` (that namespace is font-family), and the spacing scale must be `--spacing-*`, not `--space-*`. Getting these wrong generates broken or missing utilities rather than erroring.