fix(react-router): a lazy route links the page its loader picks

[colbymchenry]

Problem

A React Router data-router lazy loader resolves to the route's properties, and many loaders pick the page from the module they load:

// luci-go milo/ui, src/test_investigation/routes.ts
lazy: async () => {
  const { TestTab } = await import('@/test_investigation/components/invocation_page/tabs');
  return { Component: TestTab };
},

scanRoutes recorded only the loader's first import('…'), as lazy-import:<spec>, and resolution linked that module's default export, else its Component export. When the loader picks a member itself, that is the wrong page or none:

• milo/ui's tabs module is a barrel with neither, so its three tab routes linked nothing. These were the last 3 of the 91 failed refs fix(react-router): a lazy route links the page a barrel module forwards #2436 counted there.
• .then((m) => ({ Component: m.ReportList })), ({ Component: (await import('./reports')).ReportPage }) and const page = await import('./profile'); return { Component: page.ProfilePage } linked the module's default export, a different page.
• React Router 7's object form, lazy: { loader: async () => (await import('./show.loader')).loader, Component: async () => (await import('./show')).Show }, read the loader's module.
• A loader whose first import is not the page's (const { teamLoader } = await import('./loaders/team'); const { TeamPage } = await import('./pages/team')) read the wrong module.
• async lazy() { … }, the form React Router's docs and its own lazy-loading-router-provider example use, is a method rather than a lazy: property, so the scanner skipped it and those routes did not exist.

A GitHub code search for createBrowserRouter + lazy gave 876 router files from 834 repos, holding 2,604 lazy loaders. 468 of them are async loaders in 60 repos: 183 pick { default: Component }, and the rest pick a named page.

Fix

Reading the loader. lazyRouteReference in frameworks/react.ts reads a lazy loader the way it runs. It evaluates the loader's return value, binding what each await import(…) destructures, a module held in a variable, .then callbacks, Promise.all arrays and the v7.5 object of lazy properties. The page is the returned object's Component, or the page its element shows:

• A loader that returns the module itself keeps lazy-import:<spec>.
• A picked export becomes import:<spec>#<export>, for example import:./tabs#TestTab or import:./pages/Login#default.
• A component of the route file that the loader returns keeps its name, as a Component: field would.

When the page is not a plain binding, it is the one lazily imported export the Component or element uses, as in <AgeGate><FireworksPage /></AgeGate>, () => <PrivateRoute component={<Favorites />} /> or compose(withAuth(), layout)(Home). A loader this does not read, such as lazyPage(() => import('./x')) or .then(convert), keeps its first import, as before. One that hands over only a loader renders nothing.

Scanner changes. async lazy() { … } methods are now read. Comments are stripped first, so import(/* webpackChunkName: "x" */ './x') is no longer missed.

Ref format. import:<path>#<export> is the form Vue Router and Angular already use for a lazy component. MODULE_REFERENCE (#2422) therefore parks a failed ref under the module's module:<stem> tail unchanged, and sync retries it. Resolution goes through #2436's exportedComponent, barrels included.

The gate. React is registered before Vue Router and Angular, so resolve() and layoutComponent answer only references a React route makes (isReactRouteRef). Those are written in tsx or jsx even in a .ts routes file, and Vue's and Angular's never are. Trap 18 in framework-coverage.md records this.

Sync. lazyModules (#2452) also returns the files a picked export is read from. A sync that moves export default to another component therefore redraws a { default: Component } route, as it already does for lazy-import: routes.

Verification

Regression test. __tests__/react-router-lazy-member.test.ts has 16 tests:

• 13 index cases: each shape above, a layout from a parent's pick, the Vue Router gate, and the negatives (a loader-only loader, a pick the module lacks, { default } of a module without one).
• 3 sync cases: the module appears later, an edit adds the pick, and the picked default moves.
• On main, 15 of the 16 fail. The 16th, the moved default, passes there because main names that route lazy-import: and fix(sync): a route rendering a same-file lazy value follows its module, and a new component gets its JSX edges #2452 covers it. Here it pins that the new import:…#default form keeps that behaviour.
• Mutation checks:
  • Dropping the React-route gate fails the Vue Router test: vue/views/Login.ts by react, because React steals Vue's import:./views/Login#Login.
  • Stubbing getRetryableFailedReferences fails both retry cases.
  • Dropping the lazyModules entry fails the moved-default case.

Checks.

• tsc --noEmit is clean, and so is a strict type-check of the test file.
• 25 related test files pass, 551 tests: React, React Router, Vue/Angular routers, frameworks, and route sync.
• Full suite: 6,497 passed, 0 failed, 402 skipped (kernel-only and platform-gated).

AST oracle over the survey. The same 876 router files were parsed with the TypeScript compiler. Each lazy property, async lazy() method and <Route lazy> was evaluated on the AST with real scoping, then compared with the text reader. They agree on all 2,538 loaders that import something:

form	module	picks default	picks a named export	renders nothing
lazy: property	871	587	812	2
async lazy() method	7	73	72	1
v7.5 object form	—	6	92	—
<Route lazy>	15	—	—	—

48 loaders were decided by the "one lazily imported export" rule. I read all 48:

• 7 are <ProtectedRoute><XPage /></ProtectedRoute>.
• 11 are () => <RoleGate roles={…}><Clients /></RoleGate>.
• 3 are <AgeGate><FireworksPage /></AgeGate>.
• 1 is <PrivateRoute component={<Favorites />} />.
• 4 are createElement(module.default).
• 2 are React.createElement(RequireAuth) of a lazily imported guard, which is what those routes render.
• 2 are compose(withAuth(), layout)(Home).
• 18 are plain tags of a loaded export, such as <Page /> or <m.BasicExample />.

All 48 are right. On main, the 3 AgeGate routes linked through the default export by luck, and the 11 RoleGate ones did too.

A/B on real repos (fresh codegraph init, main fa56256c vs this branch; only react.js differs between the builds)

Controls: 26 of 28 byte-identical.

• They are fix(react-router): a lazy route links the page a barrel module forwards #2436's 21-repo kit plus ghostfolio, ngx-admin, angular-realworld, vue-realworld, vben, vue-element-admin and vue3-element-admin.
• ghostfolio is an Angular app with React detected (a package.json lists it). All 30 of its Angular lazy routes (import:…#…) stay Angular Router's.
• The two that change:
  • milo/ui: +3, the tabs.
  • React Router's own repo: +10. Its lazy-loading-router-provider example's async lazy() routes now exist, along with their 3 <Link>s. Its data-router tests' import-less lazy={async () => ({ element: <Comp /> })} routes now link Comp.

20 survey apps. These are ones with async loaders: smartbook-system (object form), qltt, pawn-shop, KomunitasDisabilitas (Promise.all), prepify-frontend, Dreamer-UI, Serviceos, morphofitfrontend, DigiShop.Frontend, jotti, iProcess, IntereSync, learn-lingo, es-covoiturage, picket-frontend, daily-writing-friends, farmap, trygc, glosse and toolbox.

• 636 picked-page edges. Each was checked against the target file's own text: 467 land on a declaration of the picked name, and 169 on what the file's export default names. None were flagged.
• 143 re-resolutions to the same node. These are lazy-import:./x → import:./x#default.
• 42 new routes from async lazy() methods.
  • IntereSync's 13 bring 25 navigate() calls that led nowhere.
  • In learn-lingo and iProcess, an index child written as a method now claims its parent's address. The parent (Main, MeasuresApp) becomes its layout rather than the page, which is how a static index child is read. These are the 2 routes "removed": the address moved to the child.
• es-covoiturage loses 2 layout edges, correctly. The parent's loader is return { loader: (await import("./pages/EventDetail")).loader }, commented "we want the loader, but not the Component here". On main, the page was the layout of the routes inside it.
• 2 apps change only in unresolved refs.
  • trygc's routes import a ./components/ folder the repo doesn't contain.
  • DigiShop's barrels re-export imports, as in import { UserLayout } from './UserLayout'; export { UserLayout }, which exportedComponent doesn't follow. Main fails the same refs as lazy-import:. See "Not in this PR".

Sync. On 8 of these apps (milo/ui, qltt, Dreamer-UI, KomunitasDisabilitas, iProcess, pawn-shop, jotti, farmap):

1. Every file a picked edge lands on was held out, 219 files in all.
2. The app was indexed, the files put back, and codegraph sync run.
3. The synced graph equals a fresh index on all 8: 0 differing lines.

Overlap

• fix(react): a component a file declares itself as a value is what its JSX renders #2420, open: its lazyImportOf parses the same shapes for React.lazy values (.then((m) => ({ default: m.Chart })), (await import('./x')).Chart). This PR's evaluator reads them too: loaderValue on the loader function, then the object's default member (or the export itself, for next/dynamic's direct .then((m) => m.Chart)). When fix(react): a component a file declares itself as a value is what its JSX renders #2420 is rebased, lazyImportOf can become that call instead of a second parser. fix(react): a component a file declares itself as a value is what its JSX renders #2420 also carries the import-forwarding barrel step DigiShop needs.
• fix(sync): a route rendering a same-file lazy value follows its module, and a new component gets its JSX edges #2452, merged: this PR extends its lazyModules to picked exports, as above.

Not in this PR

• Barrels that re-export imported bindings, import { X } from './x'; export { X } (DigiShop's @/pages and @/layout). exportedComponent follows export … from and export * but not an export clause of imports, for module-only routes as much as for picks.
• Helpers that wrap the import, such as lazyPage(() => import('./x'), 'Landing') (107 loaders in 5 repos) or loadLazyRoute(() => import('./x')), still read the module as before.

🤖 Generated with Claude Code