[PR #998] [MERGED] refactor(routing): extract App Router route graph builder #1011

New issue

Closed

opened 2026-05-06 13:11:33 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:11:33 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/998
Author: @NathanDrake2406
Created: 5/1/2026
Status: ✅ Merged
Merged: 5/2/2026
Merged by: @james-elicx

Base: main ← Head: nathan/app-route-graph-builder

📝 Commits (1)

3f2072b refactor(routing): extract App Router route graph builder

📊 Changes

3 files changed (+1369 additions, -1204 deletions)

View changed files

➕ packages/vinext/src/routing/app-route-graph.ts (+1207 -0)
📝 packages/vinext/src/routing/app-router.ts (+8 -1204)
➕ tests/app-route-graph.test.ts (+154 -0)

📄 Description

What this changes

Extracts App Router route graph construction into packages/vinext/src/routing/app-route-graph.ts.

app-router.ts now stays focused on the public appRouter() cache wrapper and request-time trie matching, while the new graph builder owns filesystem scanning, route metadata materialization, validation, synthetic parallel slot routes, and exported route shape types.

Why

Will make https://github.com/cloudflare/vinext/issues/726 easier
The App Router routing module had grown into a mixed-purpose file that combined discovery, graph materialization, cache ownership, and request matching. That made route graph changes noisy to review and more likely to collide with App Router runtime entry work.

This keeps the graph-building pressure isolated inside routing code and avoids touching generated entry templates such as entries/app-rsc-entry.ts.

Approach

Move route shape types and discovery helpers into routing/app-route-graph.ts.
Add buildAppRouteGraph(appDir, matcher) as the direct construction boundary.
Keep appRouter() behavior-compatible by delegating to the builder, then caching the returned routes as before.
Keep matchAppRoute() and trie caching in app-router.ts, since those are request-time matching concerns rather than graph construction concerns.
Add a direct graph-builder test covering pages, route handlers, layouts, and inherited parallel slots.

Validation

vp test run tests/app-route-graph.test.ts tests/routing.test.ts tests/route-sorting.test.ts tests/page-extensions-routing.test.ts
- 4 files passed, 148 tests passed
vp run vinext#build
- completed, and the build output includes dist/routing/app-route-graph.js
vp check
- passed with 1071 formatted files and no warnings, lint errors, or type errors in 457 files

Note: the first vp check run happened before the package build had generated workspace package output and failed on benchmarks/vinext/vite.config.ts resolving vinext. After vp run vinext#build, rerunning vp check passed.

Risks / follow-ups

The main risk is accidental drift in synthetic parallel slot route materialization. I covered that with the new graph-builder test plus the existing routing and route sorting suites that exercise slot inheritance, conflict errors, intercepting routes, catch-all validation, and route ordering.

No generated App Router entry files are touched in this PR.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/998 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 5/1/2026 **Status:** ✅ Merged **Merged:** 5/2/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `nathan/app-route-graph-builder` --- ### 📝 Commits (1) - [`3f2072b`](https://github.com/cloudflare/vinext/commit/3f2072b9da29a653646a46d2407fc9b67d35e95c) refactor(routing): extract App Router route graph builder ### 📊 Changes **3 files changed** (+1369 additions, -1204 deletions) <details> <summary>View changed files</summary> ➕ `packages/vinext/src/routing/app-route-graph.ts` (+1207 -0) 📝 `packages/vinext/src/routing/app-router.ts` (+8 -1204) ➕ `tests/app-route-graph.test.ts` (+154 -0) </details> ### 📄 Description ## What this changes Extracts App Router route graph construction into `packages/vinext/src/routing/app-route-graph.ts`. `app-router.ts` now stays focused on the public `appRouter()` cache wrapper and request-time trie matching, while the new graph builder owns filesystem scanning, route metadata materialization, validation, synthetic parallel slot routes, and exported route shape types. ## Why Will make https://github.com/cloudflare/vinext/issues/726 easier The App Router routing module had grown into a mixed-purpose file that combined discovery, graph materialization, cache ownership, and request matching. That made route graph changes noisy to review and more likely to collide with App Router runtime entry work. This keeps the graph-building pressure isolated inside routing code and avoids touching generated entry templates such as `entries/app-rsc-entry.ts`. ## Approach - Move route shape types and discovery helpers into `routing/app-route-graph.ts`. - Add `buildAppRouteGraph(appDir, matcher)` as the direct construction boundary. - Keep `appRouter()` behavior-compatible by delegating to the builder, then caching the returned routes as before. - Keep `matchAppRoute()` and trie caching in `app-router.ts`, since those are request-time matching concerns rather than graph construction concerns. - Add a direct graph-builder test covering pages, route handlers, layouts, and inherited parallel slots. ## Validation - `vp test run tests/app-route-graph.test.ts tests/routing.test.ts tests/route-sorting.test.ts tests/page-extensions-routing.test.ts` - 4 files passed, 148 tests passed - `vp run vinext#build` - completed, and the build output includes `dist/routing/app-route-graph.js` - `vp check` - passed with 1071 formatted files and no warnings, lint errors, or type errors in 457 files Note: the first `vp check` run happened before the package build had generated workspace package output and failed on `benchmarks/vinext/vite.config.ts` resolving `vinext`. After `vp run vinext#build`, rerunning `vp check` passed. ## Risks / follow-ups The main risk is accidental drift in synthetic parallel slot route materialization. I covered that with the new graph-builder test plus the existing routing and route sorting suites that exercise slot inheritance, conflict errors, intercepting routes, catch-all validation, and route ordering. No generated App Router entry files are touched in this PR. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>