From 087f86bcf7768a7c4908a2e2bccf1202414e15ba Mon Sep 17 00:00:00 2001 From: Chris Kehayias Date: Fri, 21 Aug 2026 05:55:09 -0400 Subject: [PATCH] docs(deps): correct the TypeScript 7 blocker with tested evidence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The typescript 7.x entry claimed TS 7 "breaks the Next.js 16 build worker". That was inherited from an undated earlier run and is wrong as of next@16.3.1 + typescript@7.0.2. Verified by attempt: - npm run build -> passes, and the TypeScript check drops from ~2.8s to 933ms on the native compiler - npm run test:run -> passes, 279/279 - npm run lint -> fails before linting a single file The real blocker is lint, and lint alone: Error: typescript-eslint does not support TS 7.0. at eslint-config-next/node_modules/typescript-eslint/dist/index.js:52 That is an explicit runtime guard, not a peer-range mismatch, so an override or --legacy-peer-deps would not help. Root cause: TypeScript 7.0 ships no compiler API at all, and typescript-eslint needs one — the 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 9.x line. Also records 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. Re-check trigger updated from "typescript-eslint widens its peer range" to the TS 7.1 release plus typescript-eslint#10940. Note ESLint 10 and TypeScript 7 are likely to unblock in the same window, since both wait on the same toolchain catching up. Trial was fully reverted: typescript@6.0.3, no invalid peers, build and lint green. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/references/deps-known-issues.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.claude/references/deps-known-issues.md b/.claude/references/deps-known-issues.md index 354140f..211da6c 100644 --- a/.claude/references/deps-known-issues.md +++ b/.claude/references/deps-known-issues.md @@ -24,7 +24,7 @@ Last audit: **2026-08-21** — report at `.claude/reports/deps-audit-2026-08-21. | Package | Target | Blocker | Verified | Re-check when | |---|---|---|---|---| -| `typescript` | 7.x | `typescript-eslint@8.67.0` (latest) caps its peer at `typescript: >=4.8.4 <6.1.0`. Staying on TypeScript 6. | 2026-08-21 | `typescript-eslint` widens its `typescript` peer range past `<6.1.0` | +| `typescript` | 7.x | **Verified by attempt 2026-08-21 (TS 7.0.2).** Lint only — `build` and `tests` both pass on TS 7. `eslint .` dies before linting anything: `Error: typescript-eslint does not support TS 7.0.` — an explicit runtime guard in `typescript-eslint/dist/index.js:52`, not merely a peer-range mismatch. Root cause: **TypeScript 7.0 ships no compiler API at all**, and typescript-eslint needs one. Both `latest` (8.67.0) and `canary` (8.67.1-alpha.24) still declare `typescript: >=4.8.4 <6.1.0`; there is no typescript-eslint 9.x line. Upstream is explicitly targeting **TS >= 7.1**, which is where the new API lands. | 2026-08-21 | typescript-eslint ships TS >= 7.1 support — track [typescript-eslint#10940](https://github.com/typescript-eslint/typescript-eslint/issues/10940) and the TS 7.1 release | | `eslint` | 10.x | **Verified by attempt, not by inference.** `eslint-config-next@16.3.1` *vendors* `eslint-plugin-react`, `eslint-plugin-import`, and `eslint-plugin-jsx-a11y` under its own `node_modules`, and all three cap `eslint` at `^9`. Installing v10 → `ERESOLVE overriding peer dependency` ×3 and `npm error invalid: eslint@10.8.1`; `eslint .` then dies with `TypeError: Error while loading rule 'react/display-name': contextOrFilename.getFilename is not a function` (`eslint-plugin-react` still calls the `context.getFilename()` API v10 removed). Zero files lintable. Reverted. | 2026-08-21 | `eslint-config-next` ships a release whose bundled `eslint-plugin-react` / `-import` / `-jsx-a11y` accept ESLint 10 | | `@types/node` | 26.x | The `@types/node` major tracks the Node major; local runtime is Node **24.18.0**. Resolved this audit by realigning **down** to `^24.13.3` (see Held). Going to 26 would put types two majors ahead of the runtime. | 2026-08-21 | Local/CI/production Node moves to 26 | @@ -32,6 +32,18 @@ Last audit: **2026-08-21** — report at `.claude/reports/deps-audit-2026-08-21. > `eslint: >=9.0.0`, which is misleading — the binding constraint lives in the plugins it bundles > under `node_modules/eslint-config-next/node_modules/`. Check those before proposing an ESLint major. +> **The inherited claim that TS 7 "breaks the Next.js 16 build worker" is wrong** — it was carried in +> from an undated earlier run and is disproven as of `next@16.3.1` + `typescript@7.0.2`. The build not +> only succeeds, it is markedly faster: the TypeScript check drops from ~2.8s to **933ms** on the +> native compiler. Next.js declares no `typescript` peer at all. The blocker is lint, and lint alone. +> +> **Partial workaround, if the faster `tsc` ever becomes worth the complexity:** TypeScript documents +> running 6 and 7 side by side via npm aliases — `"typescript": "npm:@typescript/typescript6@^6.0.2"` +> (real package, exists) plus an arbitrarily-named alias such as +> `"@typescript/native": "npm:typescript@^7.0.2"`. Anything doing `require('typescript')` then gets the +> 6.0 API — which includes Next.js's own build-time type check, so the build would go *back* to TS 6 +> speed. The win would be limited to a standalone `tsc` invocation. Not worth it for this repo today. + > **`@types/node` version numbers do not track Node patch versions.** There is no `@types/node@24.18.0` > (the highest 24.x is `24.13.3`). Writing an unsatisfiable range does not fail fast — it sends the npm > resolver into pathological backtracking (~870 CPU-seconds with no output before being killed).