TypeScript performance degrades severly with large route trees

[mrmattrc]

NOTE: I've been working with a ~5 person team and suggested Tanstack Start. It's been a fantastic DX so far, and I'm very glad we chose this as our framework. However, we've recently hit a hard limit where TS seems incapable of type checking our web app. My theory is simply that the types for RouteTree are so significant, that it always OOM errors. I also attempted to use tsgo to see if it would help speed up the type checking, but it similarly fails. I'm at a loss on how to proceed aside from removing type checking from the web app entirely. Any suggestions or assistance would be greatly appreciated! (Claude auto-generated the content below, but I'm happy to set up a more thorough example if that'd be helpful.)

GitHub Issue Draft: TypeScript Performance with Large Route Trees

Repo: TanStack/router
Title: TypeScript performance degrades severely with 379+ routes (~15M type instantiations, incompatible with tsgo)

---

Which project does this relate to?

Router / Start

Describe the bug

TypeScript performance degrades severely in applications with large route trees. Our production app with 379 registered routes experiences:

• ~28 seconds for a cold tsc --noEmit check with incremental: false
• 40+ minutes for a cold tsc --noEmit check with incremental: true (~28s checking + 39+ minutes serializing the .tsbuildinfo file for 15.4M instantiations)
• ~4 seconds for warm incremental checks (after buildinfo exists)
• 22+ GB RAM and eventual OOM when using tsgo (TypeScript Native Preview / @typescript/native-preview)
• 15.4 million type instantiations reported by tsc --diagnostics
• 8 GB heap required (NODE_OPTIONS=--max-old-space-size=8192) — default heap OOMs

The generated routeTree.gen.ts is 8,898 lines with 379 route imports, nested child interfaces, and massive union types in FileRouteTypes. Even though routeTree.gen.ts itself is excluded from typechecking via // @ts-nocheck, its types are consumed transitively through router.tsx → routeTree.gen → Register module augmentation.

Why this matters

1. tsgo incompatibility: TypeScript Native Preview (tsgo) is the future of TypeScript, offering 5-68x speedups on normal codebases. TanStack Router's type complexity makes it completely unusable — it explodes to 22+ GB RAM and never completes. This blocks adoption of tsgo for any project using TanStack Router with a non-trivial route count.

2. CI/CD impact: A 10-minute typecheck for a single app (on top of fast package checks) is a significant bottleneck. With incremental: true, cold checks balloon to 40+ minutes due to buildinfo serialization overhead.

3. Developer experience: New clones, CI runners, and cache-busted environments all hit the pathological cold-check path. The 8 GB heap requirement is unusual and can cause mysterious OOMs in constrained environments.

Your Example Website or App

Not a public repo (production SaaS), but the structure is reproducible.

Steps to Reproduce the Bug or Issue

1. Create a TanStack Start app with 300+ file-based routes across nested layout groups
2. Run tsc --noEmit --diagnostics
3. Observe type instantiation count exceeding 15 million
4. Try running tsgo --noEmit — observe 22+ GB memory usage before OOM

Our route structure

apps/web/src/routes/
├── __root.tsx
├── (user)/
│   ├── (org)/
│   │   ├── (dashboard)/
│   │   │   ├── fleet/         (~80 routes)
│   │   │   ├── loadboard/     (~60 routes)
│   │   │   ├── messages/      (~40 routes)
│   │   │   ├── settings/      (~30 routes)
│   │   │   ├── tms/           (~40 routes)
│   │   │   ├── pay/           (~20 routes)
│   │   │   ├── fuel/          (~15 routes)
│   │   │   ├── rates/         (~15 routes)
│   │   │   └── ...
│   │   └── ...
│   └── ...
├── (auth)/
└── api/

Generated routeTree.gen.ts structure (8,898 lines)

// Lines 1-389: 379 route imports
import { Route as ... } from './routes/...'

// Lines 391-3793: .update() calls establishing parent-child relationships
// Each creates a typed interface like:
interface userorgdashboardFleetRouteRouteChildren {
  userorgdashboardFleetDashboardRoute: typeof userorgdashboardFleetDashboardRoute
  userorgdashboardFleetDriversRouteRoute: typeof userorgdashboardFleetDriversRouteRouteWithChildren
  // ... many more
}

// Lines 3794-8888: The massive FileRouteTypes interface
export interface FileRouteTypes {
  fileRoutesByFullPath: FileRoutesByFullPath  // 379-entry object type
  fullPaths: '/' | '/api/health' | '/fleet' | ... // 379-entry string union
  fileRoutesByTo: FileRoutesByTo              // 379-entry object type
  to: '/' | '/api/health' | '/fleet' | ...   // 379-entry string union
  id: ... // 379-entry string union
  fileRoutesById: FileRoutesById              // 379-entry object type
}

// Lines 8890-8898: Module augmentation forcing full resolution
declare module '@tanstack/react-start' {
  interface Register {
    ssr: true
    router: Awaited<ReturnType<typeof getRouter>>  // ← triggers full tree inference
    config: Awaited<ReturnType<typeof startInstance.getOptions>>
  }
}

The key issue is that every file that imports from @tanstack/react-router (e.g., useParams, useSearch, Link, useNavigate) triggers a lookup into the Register interface, which forces TypeScript to fully resolve the entire 379-route FileRouteTypes — including all the nested child interfaces, union types, and object type maps.

router.tsx module augmentation (also triggers full resolution)

export type Router = ReturnType<typeof getRouter>

declare module '@tanstack/react-router' {
  interface Register {
    router: Router  // forces full route tree type resolution
  }
}

Expected behavior

• Type-checking should scale sub-linearly with route count, not exponentially
• A 379-route app should not generate 15.4M type instantiations
• Incremental buildinfo serialization should not take 39+ minutes when the actual check takes 28 seconds
• The type system should be compatible with tsgo (TypeScript Native Preview)
• Memory usage should stay under 4 GB for type-checking

tsc --diagnostics output (non-incremental, cold)

Files:              8,019
Lines:            1,280,936
Identifiers:      1,530,898
Symbols:          3,662,227
Types:            1,277,658
Instantiations:  15,440,445
Memory used:     3,599,621K (~3.4 GB)
I/O read:            1.23s
Parse time:          5.07s
Bind time:           1.17s
Check time:         21.56s
Emit time:           0.00s
Total time:         27.80s

With incremental: false, the cold check takes ~28 seconds — entirely reasonable. However, with incremental: true (the default inherited from our base tsconfig), cold checks balloon to 40+ minutes because serializing the .tsbuildinfo file for 15.4M instantiations is pathologically slow. This means the first typecheck after any cache bust is brutally expensive.

The 15.4 million type instantiations for a 379-route app is the core issue. For comparison, our 17 other packages (same monorepo, no TanStack Router) produce ~50K instantiations combined.

Platform

• TanStack Router: ^1.161.1
• TanStack Start: ^1.161.1
• TypeScript: 5.8.3
• tsgo: @typescript/native-preview@7.0.0-dev.20250218.1 (OOMs)
• OS: macOS (Darwin 25.2.0), Apple Silicon
• Bundler: Vite 6
• Runtime: Bun 1.2.x

Suggestions

Some potential approaches that could help:

1. Lazy type resolution: Instead of eagerly resolving all 379 routes when Register is accessed, use conditional/deferred types that only resolve the specific route being used (e.g., when useParams is called in a specific route file, only resolve that route's types).

2. Route tree type chunking: Split FileRouteTypes into smaller per-layout-group types that are composed lazily rather than as one massive union.

3. Simplified Register interface: The Awaited<ReturnType<typeof getRouter>> in the module augmentation forces full inference of the entire router creation. A simpler type reference (perhaps a pre-computed type literal) could avoid this.

4. tsgo compatibility testing: Adding tsgo to the CI matrix would catch regressions before they ship. The TypeScript team is actively working on tsgo and route-heavy apps are a perfect stress test.

5. Type complexity budget: Consider a maximum route count or type depth budget with a documented escape hatch for large apps.

Additional context

• We've migrated all other packages (17 packages + API server) to tsgo successfully — they typecheck in 2.5 seconds total. The web app with TanStack Router is the sole holdout.
• The routeTree.gen.ts file itself is correctly excluded from typechecking via // @ts-nocheck, but the types are consumed transitively through imports.
• Related issue: Params/Context type error in beforeLoad() after enabling TypeScript Native #5724 (tsgo type errors with TanStack Router)
• Related issue: [Start] Server Fn Type instantiation is excessively deep and possibly infinite error #4533 (type instantiation excessively deep)

[schiller-manuel]

can you please provide a complete reproducer project that exhibits this behavior?