typedRoutes invalid Link href is not enforced by tsc in a workspace app unless .next/types/link.d.ts is manually referenced
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.4k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 351
Description
Link to the code that reproduces this issue
https://github.com/jakeleventhal/next-typed-routes-workspace-tsc-repro
To Reproduce
- Clone the repo
- Install dependencies:
bun install
- Generate route types:
bun run -F @repro/web typegen
- Confirm the generated files:
apps/web/.next/types/routes.d.tscontains only/apps/web/.next/types/link.d.tscontains thenext/linkandnext/navigationroute augmentationsapps/web/next-env.d.tsimports./.next/types/routes.d.ts
- Run TypeScript from the app package:
bun run -F @repro/web tsc
bun run -F @repro/web tsc:noemit
- Notice that both commands succeed, even though
apps/web/src/app/page.tsxcontains an invalid route:
<Link href="/definitely-not-a-real-route">Broken typed route</Link>
- Now run the comparison script that explicitly loads the generated
link.d.tsfile:
bun run -F @repro/web tsc:with-link-augmentation
- Notice that this fails immediately with:
src/app/page.tsx(6,10): error TS2322: Type '"/definitely-not-a-real-route"' is not assignable to type 'UrlObject | RouteImpl<"/definitely-not-a-real-route">'.
Current vs. Expected behavior
Current:
typedRoutes: trueis enablednext typegengenerates bothroutes.d.tsandlink.d.ts- In this workspace-style setup, both
tsc --buildandtsc --noEmitstill accept an invalidLink href - If I manually reference
.next/types/link.d.ts, the same invalid route is rejected
Expected:
After next typegen, plain TypeScript checking should reject the invalid Link href without requiring a manual reference to .next/types/link.d.ts.
This expectation seems consistent with the docs for next typegen, which say:
next typegen && tsc --noEmit
should validate route usage externally.
Provide environment information
Operating System:
Platform: darwin
Arch: arm64
Binaries:
Node: 24.12.0
Bun: 1.3.12
Relevant Packages:
next: 16.2.4
react: 19.2.0
react-dom: 19.2.0
typescript: 5.9.3
Which area(s) are affected? (Select all that apply)
TypeScript
Which stage(s) are affected? (Select all that apply)
next typegen, tsc --build, tsc --noEmit
Additional context
The repro is intentionally a tiny monorepo/workspace because I could not reproduce this in a standalone single-package Next app. The mismatch seems to depend on a shared tsconfig package + app package setup.
The generated next-env.d.ts in the repro currently looks like this:
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
That appears to be enough for route metadata, but not enough for next/link route enforcement in this setup.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked workspace reproduction and run bun install, bun run -F @repro/web typegen, and the three TypeScript commands. Compare apps/web/next-env.d.ts, .next/types/routes.d.ts, .next/types/link.d.ts, and apps/web/src/app/page.tsx to trace which generated declarations are loaded. Done means plain tsc commands reject the invalid Link href without a manual link.d.ts reference.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bun, next.js, react, typescript
- Domain
- developer-experience, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100