Add lazy route property API, use for loading middleware #13294

markdalgleish · 2025-03-24T05:48:48Z

This removes route.unstable_lazyMiddleware in favour of a new object-based lazy API:

route.lazy = {
  unstable_middleware: () => { /* ... */ },
  ...etc
}

Lazy property functions can return null or undefined if the property is not available. This allows us to define lazy property functions even in cases where we don't know if the property is exported from the route module.

TODO:

changeset-bot · 2025-03-24T06:10:26Z

🦋 Changeset detected

Latest commit: 8c9c4ad

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
react-router	Major
@react-router/architect	Major
@react-router/cloudflare	Major
@react-router/dev	Major
react-router-dom	Major
@react-router/express	Major
@react-router/node	Major
@react-router/serve	Major
@react-router/fs-routes	Major
@react-router/remix-routes-option-adapter	Major
create-react-router	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

markdalgleish · 2025-03-30T23:10:14Z

packages/react-router/__tests__/router/context-middleware-test.ts

@@ -726,70 +734,6 @@ describe("context/middleware", () => {
          "Route property unstable_middleware is not a supported property to be returned from a lazy route function. This property will be ignored."
        );
      });
-
-      it("ignores lazy middleware returned from route.lazy", async () => {


This test was removed because route.unstable_lazyMiddleware was removed.

markdalgleish · 2025-03-30T23:13:01Z

packages/react-router/lib/dom/ssr/routes.tsx

-          invariant(
-            clientMiddlewareModule?.unstable_clientMiddleware,
-            "No `unstable_clientMiddleware` export in chunk"
+      let lazyRoutePromise:


This allows us to dedupe calls to getLazyRoute across the different lazy property loaders. This is only required because we have additional logic beyond calling await import('...').

markdalgleish · 2025-03-30T23:15:36Z

packages/react-router/lib/router/router.ts

+    if (typeof routeToUpdate.lazy === "object") {
+      routeToUpdate.lazy[key as keyof typeof routeToUpdate.lazy] = undefined;
      if (
-        !isPropertyStaticallyDefined &&
-        !unsupportedLazyRouteFunctionKeys.has(
-          lazyRouteProperty as UnsupportedLazyRouteFunctionKey
-        )
+        Object.values(routeToUpdate.lazy).every((value) => value === undefined)
      ) {
-        routeUpdates[lazyRouteProperty] =
-          lazyRoute[lazyRouteProperty as keyof typeof lazyRoute];
+        routeToUpdate.lazy = undefined;
      }
    }


We perform this cleanup because the existing route.lazy logic uses the presence of a route.lazy value to decide whether to wait on a lazy call or not.

markdalgleish · 2025-03-30T23:18:26Z

packages/react-router/lib/router/router.ts

+        if (isUnsupported) {
+          warning(
+            !isUnsupported,
+            "Route property " +
+              lazyRouteProperty +
+              " is not a supported property to be returned from a lazy route function. This property will be ignored."
+          );
+        } else if (isStaticallyDefined) {
+          warning(
+            !isStaticallyDefined,
+            `Route "${routeToUpdate.id}" has a static property "${lazyRouteProperty}" ` +
+              `defined but its lazy function is also returning a value for this property. ` +
+              `The lazy route property "${lazyRouteProperty}" will be ignored.`
+          );
+        } else {
+          routeUpdates[lazyRouteProperty] = lazyValue;


This change was made to align the approach I landed on for loading lazy route properties. This ensures that you only get a single error message with the most relevant information. Most notably, if you have an unsupported key in your route.lazy object (e.g. id) then it's irrelevant that it's also statically defined since we'll never use the lazy value anyway.

markdalgleish · 2025-03-30T23:20:28Z

packages/react-router/lib/router/utils.ts

+export type LazyRouteObject<R extends AgnosticRouteObject> = {
+  [K in keyof R as K extends UnsupportedLazyRouteObjectKey
+    ? never
+    : K]?: () => Promise<R[K] | null | undefined>;


Just calling this out as a discussion point since it's public API — lazy property functions are always async and can return null or undefined.

brophdawg11

Code looks good! Gonna pull and do some testing now...

brophdawg11 · 2025-03-31T18:07:52Z

docs/start/data/custom.md

+      action: async () =>
+        (await import("./show.action.js")).action,
+      Component: async () =>
+        (await import("./show.component.js")).Component,


huh - I didn't realize our docs showed this type of granular file splitting. I feel like the more common use case is lazy: () => import("./route") so I would actually vote to document that version with a note on how to get more granular if/when needed

I feel this is the better API to document because it handles all properties, whereas the lazy function can't handle middleware. I also feel like this version is a bit clearer in terms of what's going on.

brophdawg11 · 2025-03-31T18:33:43Z

packages/react-router/lib/dom/ssr/routes.tsx

+        loader:
+          dataRoute.loader || !route.hasClientLoader
+            ? undefined
+            : async () => {


I think I expected to see the if (route.clientLoaderModule) logic above moving down into route.lazy.loader as well? I think it would be another split in this conditional (using if/else for readability now that it has 3 branches). It might nicely colocate all of our loader initialization whereas we used to have 2 spots (outside/inside of lazy)

// assume `dataRoute.lazy` is initialized as an empty object above - may not // be the way we want to do it but it might read nicely as we build up the // route object and let us colocate initialization logic per-field... if (!route.hasClientLoader) { // No `clientLoader` exists, use the `loader` to load styles and call the // server `loader` (if it exists) in parallel with `route.lazy` execution dataRoute.loader = (_: LoaderFunctionArgs, singleFetch?: unknown) => prefetchStylesAndCallHandler(() => { return fetchServerLoader(singleFetch); }); } else if (route.clientLoaderModule) { // A `clientLoader` module exists, load it with route.lazy.loader dataRoute.lazy.loader = async () => { invariant(route.clientLoaderModule); let { clientLoader } = await import( /* @vite-ignore */ /* webpackIgnore: true */ route.clientLoaderModule ); return (args: LoaderFunctionArgs, singleFetch?: unknown) => clientLoader({ ...args, async serverLoader() { preventInvalidServerHandlerCall("loader", route); return fetchServerLoader(singleFetch); }, }); }; } else { // No `clientLoader` module exists, load the `clientLoader` via the // full route module dataRoute.lazy.loader = async () => { let { clientLoader } = await getLazyRoute(); invariant(clientLoader, "No `clientLoader` export found"); // This below is the same as above so may be able to be shared. // All that differs between this and the conditional branch above is // where we get `clientLoader` from... return (args: LoaderFunctionArgs, singleFetch?: unknown) => clientLoader({ ...args, async serverLoader() { preventInvalidServerHandlerCall("loader", route); return fetchServerLoader(singleFetch); }, }); }; }

Thanks for catching this, I've pushed a refactor that cleans this up.

brophdawg11 · 2025-03-31T18:45:26Z

packages/react-router/lib/router/router.ts

    m.route.lazy
-      ? loadLazyRouteModule(m.route, mapRouteProperties, manifest)
+      ? loadLazyRoute(m.route, manifest, mapRouteProperties)


This will run all lazy.* functions here right? I think that's the right approach to start - but curious if you were thinking we should take it farther/more granular and do the type of stuff we do in framework mode for library mode where we skip the hydrate fallback if we're not hydrating?

Yep, I wanted to do that as a follow-up.

github-actions · 2025-04-02T14:57:29Z

🤖 Hello there,

We just published version 7.5.0-pre.0 which includes this pull request. If you'd like to take it for a test run please try it out and let us know what you think!

Thanks!

…d-route-typegen * upstream/dev: (56 commits) chore: format feat: unstable_subResourceIntegrity (remix-run#13163) Add lazy route property API, use for loading middleware (remix-run#13294) Add `rolldown-vite` playground (remix-run#13333) chore: Update version for release (remix-run#13322) Exit prerelease mode Update release notes Remove `react-router:override-optimize-deps` plugin (remix-run#13317) chore: format Add Wrangler v4 to `@react-router/dev` peer dep range (remix-run#13258) update changelog Handle custom base for critical CSS with Vite Env API (remix-run#13305) chore: Update version for release (pre) (remix-run#13312) Enter prerelease mode chore: format host parse (remix-run#13309) Fix middleware return types (remix-run#13311) more data docs fix Location link (remix-run#13291) Also fix the meta link ...

github-actions · 2025-04-04T18:20:35Z

🤖 Hello there,

We just published version 7.5.0 which includes this pull request. If you'd like to take it for a test run please try it out and let us know what you think!

Thanks!

Add initial lazy property logic

e29c07b

remix-cla-bot bot added the CLA Signed label Mar 24, 2025

Fix type errors

9d5e920

markdalgleish added 11 commits March 24, 2025 17:16

Remove outdated test for unstable_lazyMiddleware check

1ef679b

Add tests for falsy lazy properties

8cc1b2b

Add tests for unsupported properties, refactor

adda7b7

Hook lazy property API up to framework

18c8733

Clean up redundant await

4ec8ed3

Unify lazy route property loading logic

f0d3b89

Improve lazy route property types

a61207a

Fix null and undefined check

9c48bb8

Update docs

55e1d27

Merge branch 'dev' into markdalgleish/lazy-route-properties

04287d2

Update changeset

4366a72

markdalgleish added pkg:react-router pkg:@react-router/dev labels Mar 27, 2025

markdalgleish changed the title ~~WIP: Add lazy route property API~~ Add lazy route property API, use for loading middleware Mar 27, 2025

Refactor

2a16477

markdalgleish marked this pull request as ready for review March 27, 2025 04:25

Merge branch 'dev' into markdalgleish/lazy-route-properties

ad8ce76

markdalgleish commented Mar 30, 2025

View reviewed changes

brophdawg11 reviewed Mar 31, 2025

View reviewed changes

Simplify clientLoader/Action logic, refactor

8c9c4ad

markdalgleish merged commit d07cefe into dev Apr 1, 2025
5 checks passed

markdalgleish deleted the markdalgleish/lazy-route-properties branch April 1, 2025 02:48

github-actions bot mentioned this pull request Apr 2, 2025

chore: Update version for release (pre) #13345

Merged

github-actions bot mentioned this pull request Apr 4, 2025

chore: Update version for release #13366

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add lazy route property API, use for loading middleware #13294

Add lazy route property API, use for loading middleware #13294

markdalgleish commented Mar 24, 2025 •

edited

Loading

changeset-bot bot commented Mar 24, 2025 •

edited

Loading

markdalgleish Mar 30, 2025

markdalgleish Mar 30, 2025

markdalgleish Mar 30, 2025

markdalgleish Mar 30, 2025 •

edited

Loading

markdalgleish Mar 30, 2025

brophdawg11 left a comment

brophdawg11 Mar 31, 2025

markdalgleish Apr 1, 2025

brophdawg11 Mar 31, 2025

markdalgleish Mar 31, 2025

brophdawg11 Mar 31, 2025

markdalgleish Mar 31, 2025

github-actions bot commented Apr 2, 2025

github-actions bot commented Apr 4, 2025

Add lazy route property API, use for loading middleware #13294

Add lazy route property API, use for loading middleware #13294

Conversation

markdalgleish commented Mar 24, 2025 • edited Loading

changeset-bot bot commented Mar 24, 2025 • edited Loading

🦋 Changeset detected

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markdalgleish Mar 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brophdawg11 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 2, 2025

github-actions bot commented Apr 4, 2025

markdalgleish commented Mar 24, 2025 •

edited

Loading

changeset-bot bot commented Mar 24, 2025 •

edited

Loading

markdalgleish Mar 30, 2025 •

edited

Loading