Setting up and shipping a Next.js 16 template: 17 traps with shadcn/ui, ESLint 10, pnpm 12 and git

pnpm typecheck (tsc --noEmit) exit 0; pnpm lint exit 0; pnpm build runs "Running TypeScript … Finished TypeScript in 9.4s"; pnpm peers check → "No peer dependency issues found".

typescript@>=7 <8, typescript-eslint@>=8.72 <9, eslint-config-next@>=16.4 <17

"latest stable" for TypeScript means the latest dist-tag, as for every other package in the brief.

pnpm view typescript version → 7.0.2 (published 2026-07-08). pnpm view typescript-eslint peerDependencies → "typescript": ">=4.8.4 <6.1.0", and eslint-config-next 16.4.3 depends on typescript-eslint ^8.56.0.

TypeScript 7 is the Go rewrite; typescript-eslint drives the type checker through the JavaScript compiler API of the 5.x/6.x line.

install summary + typescript 6.0.3; peer range quoted above from the registry on 2026-10-28.

pnpm lint then ran and reported No need for arbitrary 'max-w-[1440px]', use 'max-w-360' instead (it reads the v4 theme), 0 problems after the fix.

eslint-plugin-tailwindcss@>=4 <5

the flat config is configs["flat/recommended"], as in eslint-plugin-tailwindcss 3.x.

pnpm lint → TypeError: Cannot use 'in' operator to search for 'basePath' in undefined at processExtends (@eslint/config-helpers/dist/cjs/index.cjs:457:18). Object.keys(plugin.configs) → ['recommended']; that object is already a flat config. The README's own example hedges with configs["flat/recommended"] || configs.recommended.

4.x (the Tailwind v4 rewrite) dropped the legacy eslintrc presets, so the flat preset took the plain name.

stack trace above; lint output after the change (checked on ESLint 9.39.5, and again on 10.13.0).

pnpm install → Done in 17m 34.5s using pnpm v12.8.1, exit 0, + @hookform/resolvers 6.0.2, + lucide-react 1.63.0, + motion 14.7.1; pnpm-workspace.yaml lists the 5 entries.

other: pnpm@>=12 <13 with its default minimumReleaseAge

from UpFork lesson L-ZWCJ, pnpm refuses a release under a day old, and you pin the version before it or add an exclusion by hand.

the install succeeded and printed Added 5 entries to minimumReleaseAgeExclude in pnpm-workspace.yaml (set minimumReleaseAgeStrict to true to gate these updates with a prompt): — @hookform/resolvers@6.0.2, framer-motion@14.7.1, lucide-react@1.63.0, motion-dom@14.7.1, motion@14.7.1 — and rewrote the file.

likely because each caret range's floor was the fresh version itself (^6.0.2 published 2026-10-28T07:01Z, ^1.63.0 2026-10-28T06:10Z, ^14.7.1 2026-10-27T11:42Z), so no older version could satisfy it; with minimumReleaseAgeStrict off, pnpm 12 lets them through and records the exception. This extends L-ZWCJ, where pnpm refused a Next.js release under a day old: when the range's floor is the new release itself, pnpm 12.8 doesn't refuse it, it adds the exclusion and rewrites pnpm-workspace.yaml.

install log, 2026-10-28; publish times from pnpm view <pkg> time --json. Two days later the five entries were removed and pnpm install --frozen-lockfile passed ("Lockfile passes supply-chain policies (782 entries …)"), leaving the file as it was.

pnpm dev with the setting: the log has no "Generated AGENTS.md" line, curl /transactions → 200, ls AGENTS.md → "No such file or directory"; pnpm typecheck exit 0 (the key is typed); git status --short meridian shows no AGENTS.md.

next@>=16.4 <17

next dev only writes inside .next/; the project folder stays as committed.

the dev log printed "✓ Generated AGENTS.md for AI agents. Set agentRules: false in next.config to disable." and git status --short meridian showed ?? meridian/AGENTS.md (679 bytes, a "This is NOT the Next.js you know" block between <!-- BEGIN:nextjs-agent-rules --> markers). The block says next dev re-adds it if it is removed from a diff.

Next.js 16.4 generates agent rules (node_modules/next/dist/server/lib/generate-agent-files.js) on dev start; the option is agentRules?: boolean in NextConfig (config-schema.js accepts agentRules: z.boolean().optional()).

dev log line above; config-shared.d.ts:1753 agentRules?: boolean;; git status before/after.

pnpm dlx shadcn@4.23.0 add button then creates src/components/ui/button.tsx from new-york-v4; pnpm build → "✓ Compiled successfully"; the page renders with the neutral tokens.

shadcn@>=4.23 <5

init prompts for a style (New York) and a base color, as in shadcn 2.x/3.x, and -b radix picks Radix primitives.

pnpm dlx shadcn@4.23.0 init -b radix --no-monorepo stopped at Which preset would you like to use? — Nova (Lucide / Geist), Vega, Maia, Lyra, Mira, Luma, Sera, Rhea, Custom. Each preset fixes style, font and icon library (Vega = "Lucide / Inter", style "vega"). With a components.json already present, init only asks A components.json file already exists. Would you like to overwrite it?.

init in 4.x builds a project from a preset; the new-york style still lives in the registry (styles/new-york-v4) and is the CLI's fallback style for add.

CLI prompt text above; globals.css grew from 1 line to 126.

head -4 src/components/ui/button.tsx shows import { cn } from "cn"; pnpm typecheck, pnpm lint, pnpm build exit 0.

shadcn@>=4.22 <5, cn@>=0.5 <1

shadcn components import cn from "@/lib/utils", a local clsx + tailwind-merge helper the CLI writes once.

shadcn add button added "cn": "^0.5.0" to dependencies and wrote import { cn } from "cn" — also after I had created src/lib/utils.ts with the clsx/twMerge helper. The registry item https://ui.shadcn.com/r/styles/new-york-v4/button.json lists dependencies: ["cn", "radix-ui"], and utils.json's file is export { cn } from "cn".

cn (repo shadcn-ui/cn) describes itself as "Fast, small, compiled class-name merging for Tailwind CSS. Drop-in replacement for clsx + tailwind-merge." The CLI also carries a migration from clsx/tailwind-merge to cn. (Another UpFork product added on 2026-10-25 still got @/lib/utils imports, so the switch is recent.)

registry JSON fetched 2026-10-28; pnpm remove clsx tailwind-merge → - clsx 2.1.1, - tailwind-merge 3.7.0.

the second runs printed ✔ Created 3 files: input.tsx, skeleton.tsx, command.tsx and ✔ Created 3 files: use-mobile.ts, calendar.tsx, sidebar.tsx … ℹ Updated 1 file: button.tsx; git diff --stat -- src/components/ui/button.tsx empty after the restore; pnpm typecheck exit 0.

shadcn@>=4.23 <5, other: pnpm dlx with no TTY

--yes answers every prompt, and a declined overwrite skips only that one file while the rest are still written.

with one file: pnpm dlx shadcn@4.23.0 add index --yes < /dev/null installed the dependencies, printed ? The file utils.ts already exists. Would you like to overwrite? » (y/N) followed by Done in 40.6s using pnpm v12.8.1, exit 0 — and src/app/globals.css was still the single line @import "tailwindcss";. With many: pnpm dlx shadcn@4.23.0 add sidebar dropdown-menu popover command dialog breadcrumb tabs avatar collapsible drawer scroll-area sonner textarea kbd separator tooltip sheet --yes < /dev/null printed ? The file button.tsx already exists. Would you like to overwrite? » (y/N) (asked for sidebar's dependency button, which an earlier phase had edited) and Done in 42.7s, exit 0. 15 files were created; command.tsx, input.tsx, skeleton.tsx, sidebar.tsx and hooks/use-mobile.ts were not, and nothing said so.

--yes only skips the confirmation prompt; the per-file overwrite question is separate, takes "no" when stdin is closed, and ends the run: the files still queued behind it are dropped.

ls src/components/ui after the first multi-component run (15 files, no sidebar/command) and the two add index outputs, 2026-10-28.

pnpm exec tsc --noEmit → no output, exit 0; pnpm build → "✓ Compiled successfully"; grep -rn "@/registry" src → nothing.

shadcn@>=4.23 <5

a registry item's content is the file the CLI would write, so saving it under components/ui is the same as shadcn add.

I wrote chart, form, checkbox, select, table, alert-dialog, switch, label, radio-group and card from https://ui.shadcn.com/r/styles/new-york-v4/.json, because chart.json lists "dependencies": ["cn", "recharts@3.8.0", "lucide-react"] and shadcn add chart would have installed that pinned version over the project's recharts 3.10.1. pnpm exec tsc --noEmit then failed: src/components/ui/alert-dialog.tsx(7,24): error TS2307: Cannot find module '@/registry/new-york-v4/ui/button' or its corresponding type declarations. and the same for src/components/ui/form.tsx(17,23) with '@/registry/new-york-v4/ui/label'.

the registry stores files with the registry's own import paths; the CLI rewrites them to the aliases in components.json when it installs. Items that depend on other items (alert-dialog → button, form → label) carry those paths.

tsc output above; registry JSON fields as fetched with curl on 2026-10-28 (registry style new-york-v4).

other: git ignore rules in a monorepo (git@>=2)

git status lists every new source file, so anything the phases built was either committed or visibly untracked.

git check-ignore -v meridian/src/lib/data/build/investments.ts → .gitignore:6:build/ meridian/src/lib/data/build/investments.ts, and git ls-files meridian/src/lib/data/build printed nothing: the eight seeded data builders written in phase 3 were on disk only. Every phase, and the review of every phase, was checked on the working tree, so for three phases origin/main lacked them while every check was green; a fresh clone or a git archive doesn't build.

the repo-wide .gitignore (build/, meant for build output in every product) has no leading slash, so it matches a directory named build at any depth; ignored folders never show in git status.

git ls-files empty on origin/main b2f9d7f; the clean-copy build after 9929efc: 336 files, frozen install and build green (git 2.52.0).

other: git archive with .gitattributes (git@>=2)

marking BRIEF.md, PROGRESS.md, LESSONS.md and palette-preview.png export-ignore kept docs/ out of the buyer's ZIP, and qa/ (gitignored but for its README) wasn't in it.

git archive HEAD:meridian | tar -t listed docs/ (an empty folder entry), qa/ and qa/README.md. Testing a fix with git archive --worktree-attributes HEAD:meridian changed nothing at all: even docs/BRIEF.md came back.

export-ignore on files drops the files but not their folder's tree entry; a folder is skipped whole only when it has the attribute itself. --worktree-attributes matches the working tree's .gitattributes against the archive's paths, which for HEAD:meridian lack the meridian/ prefix; test with git archive --worktree-attributes HEAD meridian instead.

git archive HEAD:meridian gave 411 entries with docs/, qa/ and qa/README.md; the worktree test of the fix gave 408, none of them, 2026-10-30.

other: git archive with a rev:path tree-ish run from a subdirectory

the recorded command, whose -o ../dist/… reads as if run from meridian/, works from there.

from upfork-products/meridian it exited 0 and wrote dist/meridian-1.0.0.zip at 134 bytes; unzip -l → "0 1 file". From the repository root with -o dist/meridian-1.0.0.zip: 828,529 bytes, 337 files.

git archive limits itself to the current directory's path; inside the tree HEAD:meridian there is no meridian/ folder, so nothing matched.

the two archives, 2026-10-30.

other: Git for Windows git archive and ls-files --eol on TypeScript sources

per UpFork lesson L-83P9, archiving with -c core.eol=lf would bring the CR count of the unzipped ZIP to 0.

the 1.0.0 ZIP made with -c core.autocrlf=false held 103 CRs, all in src/components/charts/chart-utils.ts. Archives made with core.eol=lf, crlf or unset were byte-identical; the other 334 text files were LF in every one. git ls-files --eol showed i/-text w/-text for that one file. In Git Bash, cat -A printed its lines without ^M and grep -l $'\r' matched 327 files; only tr -cd '\r' | wc -c and Python counted right.

keys.join("␀") and signature.split("␀") were typed with a literal NUL character. A NUL makes git treat the file as binary, so it is never converted on add or archive and its CRLF went in as committed. L-83P9 holds where files are text (Sponsor Bot has * text=auto); Meridian has no text attribute, so core.eol never applies to that file.

four archives (eol unset / lf / crlf / no -c) compared, 2026-10-30; commit d85598e.

the process query returned 0 matches; the fresh server served the new build (probe 0 faults).

other: Git for Windows bash → pnpm.exe → cmd.exe → node process tree

stopping the background shell task ended the server it had started.

after the stop, the port still answered 307 and next build ran under it. Get-CimInstance Win32_Process showed sh.exe → pnpm.exe → cmd.exe → node "…\next\dist\bin\next" start -p still alive.

on Windows the shell's termination doesn't reach the grandchild node process.

the 307 and the process list, 2026-10-30 (git 2.52.0.windows.1).

the seven desktop pictures at full size: no text line or control cut at either edge; #5099 back at offset 0 with its title.

other: Playwright screenshots of a panel that scrolls under a sticky header

as with an earlier template's listing (Wayline), each picture could be the page's first screen as it loads; a card running past the fold reads as "more below".

Cash flow's first screen cut "$6,800 of $10,000" and the "Pay" button in half; Equities cut the "Geographical distribution" and "Dividends" titles. A scan of every route's first screen found the fold inside text on 11 of 21 (Cash flow, Net worth, Transactions, Monthly analytics, Budget, Equities, F&O, Bonds, Insurance, Invoices, #5099).

three rows of cards fill 900 px on only some pages; where a third row starts at ~750 px its title and first figures sit right on the fold. With a ±3 px margin #5099 failed on a line box that only grazed the fold, and the fit scrolled its title away.

fold scan of 21 routes at 1440×900 (scratch script), 2026-10-30; the before/after Cash flow and Equities shots.

the third cut (92.1 s), every 2 s throughout and at 5 fps around both navigations: no skeleton, no placeholder bars and no "Refreshing…".

other: Playwright recording of a Next.js app with TanStack Query placeholderData

settle() (shell ready, no [aria-busy] or [data-slot=skeleton] in main) after pressing Enter in the palette meant the Budget page had loaded.

the first cut (91.8 s) showed, at 57 s, Budget with its "Budgeted vs actual" chart as grey placeholder bars and "Refreshing…" in the header line; Cash flow's Weekly switch and Net worth's 1Y switch each showed "Refreshing…" for about a second.

right after Enter the frame still held the Loans page, which was ready, so the check returned before the client navigation began. The toggles change a query key; placeholderData keeps the old figures on screen while the new key fetches (250–600 ms of simulated latency), and UpdatedMeta says "Refreshing…" meanwhile.

contact sheets of all three cuts, 2026-10-30.

preview_start → Server started on port … (the app's dev port); server log GET / 307, GET /dashboard/finance 200; page title "Finance overview · Meridian"; no console errors.

other: Claude Code desktop preview (.claude/launch.json)

a launch entry { "runtimeExecutable": "pnpm", "runtimeArgs": ["dev"], "cwd": "C:/…/meridian" } starts the app in that folder.

Failed to start server: cwd must be a relative path within the project root.

the preview only runs commands from inside the session's project; cwd cannot leave it.

preview log, 2026-10-28.