docs(deps): correct the TypeScript 7 blocker with tested evidence

[chriskehayias]

Follow-up to #69. Docs only — no dependency or source changes.

Why

The typescript 7.x row in .claude/references/deps-known-issues.md claimed TS 7 "breaks the Next.js 16 build worker." That was inherited from an undated earlier audit run and is wrong as of next@16.3.1 + typescript@7.0.2. A wrong entry in that file is worse than no entry — it is explicitly the state future /audit-deps runs trust instead of re-deriving.

Verified by attempt

Installed typescript@^7.0.2 and ran the full suite:

Command	Result
npm run build	pass — and the TypeScript check drops from ~2.8s to 933ms on the native compiler
npm run test:run	pass — 279/279
npm run lint	fail, before linting a single file

Error: typescript-eslint does not support TS 7.0.
    at eslint-config-next/node_modules/typescript-eslint/dist/index.js:52

So the blocker is lint, and lint alone. Next.js declares no typescript peer at all, and the build is not merely fine but measurably faster.

Root cause

That message comes from an explicit runtime guard, not a peer-range mismatch — an overrides entry or --legacy-peer-deps would not help.

TypeScript 7.0 ships no compiler API at all. It is the native rewrite and the programmatic interface did not come with it; typescript-eslint requires that API, so it hard-refuses. Same reason Vue, MDX, Astro, Svelte, and Angular tooling cannot use TS 7 yet. The new API is slated for TS 7.1, and typescript-eslint is explicitly targeting >= 7.1 — typescript-eslint#10940.

Neither latest (8.67.0) nor canary (8.67.1-alpha.24) has moved off typescript: >=4.8.4 <6.1.0, and there is no typescript-eslint 9.x line.

Also recorded

The documented TS 6/7 side-by-side alias workaround, and why it is not worth taking here: aliasing typescript to @typescript/typescript6 means anything calling require('typescript') gets the 6.0 API — including Next.js's own build-time type check — so the build returns to TS 6 speed and the only gain is a standalone tsc.

The re-check trigger changes from the vague "typescript-eslint widens its peer range" to the concrete TS 7.1 release plus that tracking issue. Note that ESLint 10 and TypeScript 7 are likely to unblock in the same window, since both wait on the same toolchain catching up.

Safety

The TS 7 trial was fully reverted before this commit: typescript@6.0.3, no invalid: peers, build and lint green, working tree clean. This PR touches one Markdown file.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!