package.json & pnpm config
1. Scripts organization
Separator keys — unused JSON keys as section dividers: "// ── Name ───…": "", padded with ─ to ~50 chars, placed before the first script of each section.
"// ── Core ─────────────────────────────────────────": "",
"dev": "next dev",
"build": "next build",
"// ── Testing ─────────────────────────────────────": "",
"test": "jest"
Multi-process commands — when a script starts 2+ background processes, extract it to scripts/*.sh from the template scripts/multi-process-dev.sh.template (trap-based cleanup so Ctrl+C takes every child down). chmod +x it.
Multi-environment dev:
"// ── Dev with API (3 environments) ───────────────": "",
"dev:full": "API_MODE=local ./scripts/dev-full.sh",
"dev:full:preview": "API_MODE=preview pnpm dev",
"dev:full:prod": "API_MODE=production pnpm dev"
Section names, suffix conventions, monorepo namespace prefixes, _ internal scripts: references/patterns.md.
2. Serve / dev scripts
Read references/serve-scripts.md before changing any server-starting script. It covers:
--kill—preXXXhook:lsof -ti :PORT | xargs kill 2>/dev/null; true(multiple ports: repeat-ti :PORT, never:A,:B)--net—COMMAND:netvariants bound to0.0.0.0, per-framework host flags--rotate— non-destructive port rotation: copyassets/find-free-port.mjs(verbatim) +assets/dev-launcher.mjsinto the project; multi-process variant in references/port-rotation-multi-process.md
Invoked with no flag and no clear intent: ask which tweak to apply. Prefer rotation over kill when worktrees/second checkouts run side by side or the port may belong to something the user wants alive.
3. pnpm version via corepack
Pin in package.json: "packageManager": "pnpm@10.30.2+sha512.…". Once per machine: corepack enable.
- Node ≥25 no longer bundles corepack —
npm install -g corepackfirst, or use pnpm's standalone installer (curl -fsSL https://get.pnpm.io/install.sh | sh -); recent pnpm readspackageManagerand self-manages the pinned version. - Never
pnpm self-update— it errors under corepack. - Never add
corepack use pnpm@latestto setup steps (a common AI/automation mistake) — it bumpspackageManagerand churnspnpm-lock.yaml. Upgrade only intentionally: one person runscorepack use pnpm@<version>and commits package.json + lockfile.
4. Dependency build-script security
pnpm 10+ blocks dependency lifecycle scripts by default. Verdicts go in the allowBuilds map in pnpm-workspace.yaml (true = run, false = deny + silence the warning) — NOT .npmrc, where such keys are silent no-ops. Never bulk-approve; evaluate each package.
Workflow for "Ignored build scripts" warnings, decision criteria, known-package verdict table, strictDepBuilds: references/build-scripts.md.