Feat: Add deferred support

.changeset/light-months-argue.md

@@ -0,0 +1,68 @@
+---
+"react-router": patch
+"@remix-run/router": patch
+---
+
+Feat: adds `deferred` support to data routers
+
+Returning a `deferred` from a `loader` allows you to separate _critical_ loader data that you want to wait for prior to rendering the destination page from _non-critical_ data that you are OK to show a spinner for until it loads.
+
+```jsx
+// In your route loader, return a deferred() and choose per-key whether to
+// await the promise or not.  As soon as the awaited promises resolve, the
+// page will be rendered.
+function loader() {
+  return deferred({
+    critical: await getCriticalData(),
+    lazy1: getLazyData(),
+  });
+};
+
+// In your route element, grab the values from useLoaderData and render them
+// with <Deferred>
+function DeferredPage() {
+  let data = useLoaderData();
+  return (
+    <>
+      <p>Critical Data: {data.critical}</p>
+      <Deferred
+        data={data.lazy}
+        fallback={<p>Loading...</p>}
+        errorBoundary={<RenderDeferredError />}>
+        <RenderDeferredData />
+      </Deferred>
+    </>
+  );
+}
+
+// Use separate components to render the data once it resolves, and access it
+// via the useDeferred hook
+function RenderDeferredData() {
+  let data = useDeferred();
+  return <p>Lazy: {data}</p>;
+}
+
+function RenderDeferredError() {
+  let data = useDeferred();
+  return (<p>Error! {data.message} {data.stack}</p>;
+}
+```
+
+If you want to skip the separate components, you can use the Render Props
+pattern and handle the rendering inline:
+
+```jsx
+function DeferredPage() {
+  let data = useLoaderData();
+  return (
+    <>
+      <p>Critical Data: {data.critical}</p>
+      <Deferred data={data.lazy} fallback={<p>Loading...</p>}>
+        {({ data }) =>
+          isDeferredError(data) ? <p>Error! {data.message}</p> : <p>{data}</p>
+        }
+      </Deferred>
+    </>
+  );
+}
+```

examples/data-router/src/App.tsx

@@ -1,11 +1,19 @@
 import React from "react";
-import type { ActionFunction, LoaderFunction } from "react-router-dom";
+import {
+  ActionFunction,
+  isDeferredError,
+  LoaderFunction,
+  useRevalidator,
+} from "react-router-dom";
 import {
   DataBrowserRouter,
+  Deferred,
   Form,
   Link,
   Route,
   Outlet,
+  deferred,
+  useDeferred,
   useFetcher,
   useFetchers,
   useLoaderData,
@@ -17,7 +25,7 @@ import {
 import type { Todos } from "./todos";
 import { addTodo, deleteTodo, getTodos } from "./todos";
 
-let sleep = () => new Promise((r) => setTimeout(r, 500));
+let sleep = (n: number = 500) => new Promise((r) => setTimeout(r, n));
 
 function Fallback() {
   return <p>Performing initial data "load"</p>;
@@ -26,6 +34,7 @@ function Fallback() {
 // Layout
 function Layout() {
   let navigation = useNavigation();
+  let { revalidate } = useRevalidator();
   let fetchers = useFetchers();
   let fetcherInProgress = fetchers.some((f) =>
     ["loading", "submitting"].includes(f.state)
@@ -37,7 +46,15 @@ function Layout() {
         &nbsp;|&nbsp;
         <Link to="/todos">Todos</Link>
         &nbsp;|&nbsp;
+        <Link to="/deferred">Deferred</Link>
+        &nbsp;|&nbsp;
+        <Link to="/deferred/child">Deferred Child</Link>
+        &nbsp;|&nbsp;
+        <Link to="/long-load">Long Load</Link>
+        &nbsp;|&nbsp;
         <Link to="/404">404 Link</Link>
+        &nbsp;&nbsp;
+        <button onClick={() => revalidate()}>Revalidate</button>
       </nav>
       <div style={{ position: "fixed", top: 0, right: 0 }}>
         {navigation.state !== "idle" && <p>Navigation in progress...</p>}
@@ -47,6 +64,10 @@ function Layout() {
         Click on over to <Link to="/todos">/todos</Link> and check out these
         data loading APIs!{" "}
       </p>
+      <p>
+        Or, checkout <Link to="/deferred">/deferred</Link> to see how to
+        separate critical and lazily loaded data in your loaders.
+      </p>
       <p>
         We've introduced some fake async-aspects of routing here, so Keep an eye
         on the top-right hand corner to see when we're actively navigating.
@@ -192,6 +213,9 @@ function TodoItem({ id, todo }: TodoItemProps) {
 const todoLoader: LoaderFunction = async ({ params }) => {
   await sleep();
   let todos = getTodos();
+  if (!params.id) {
+    throw new Error("Expected params.id");
+  }
   let todo = todos[params.id];
   if (!todo) {
     throw new Error(`Uh oh, I couldn't find a todo with id "${params.id}"`);
@@ -211,11 +235,121 @@ function Todo() {
   );
 }
 
+const deferredLoader: LoaderFunction = async ({ request }) => {
+  return deferred({
+    critical1: await new Promise((r) =>
+      setTimeout(() => r("Critical Data 1"), 250)
+    ),
+    critical2: await new Promise((r) =>
+      setTimeout(() => r("Critical Data 2"), 500)
+    ),
+    lazyResolved: Promise.resolve("Lazy Data immediately resolved"),
+    lazy1: new Promise((r) => setTimeout(() => r("Lazy Data 1"), 1000)),
+    lazy2: new Promise((r) => setTimeout(() => r("Lazy Data 2"), 1500)),
+    lazy3: new Promise((r) => setTimeout(() => r("Lazy Data 3"), 2000)),
+    lazyError1: new Promise((_, r) => setTimeout(() => r("Kaboom!"), 2500)),
+    lazyError2: new Promise((_, r) => setTimeout(() => r("Kaboom!"), 3000)),
+  });
+};
+
+function DeferredPage() {
+  let data = useLoaderData();
+  return (
+    <div>
+      <p>{data.critical1}</p>
+      <p>{data.critical2}</p>
+      <Deferred data={data.lazyResolved} fallback={<p>should not see me!</p>}>
+        <RenderDeferredData />
+      </Deferred>
+      <Deferred data={data.lazy1} fallback={<p>loading 1...</p>}>
+        <RenderDeferredData />
+      </Deferred>
+      <Deferred data={data.lazy2} fallback={<p>loading 2...</p>}>
+        <RenderDeferredData />
+      </Deferred>
+      <Deferred data={data.lazy3} fallback={<p>loading 3...</p>}>
+        {({ data }: { data: any }) => <p>{data}</p>}
+      </Deferred>
+      <Deferred data={data.lazyError1} fallback={<p>loading (error 1)...</p>}>
+        <RenderDeferredData />
+      </Deferred>
+      <Deferred
+        data={data.lazyError2}
+        fallback={<p>loading (error 2)...</p>}
+        errorBoundary={<RenderDeferredError />}
+      >
+        <RenderDeferredData />
+      </Deferred>
+      <Outlet />
+    </div>
+  );
+}
+
+const deferredChildLoader: LoaderFunction = async ({ request }) => {
+  return deferred({
+    critical: await new Promise((r) =>
+      setTimeout(() => r("Critical Child Data"), 500)
+    ),
+    lazy: new Promise((r) => setTimeout(() => r("Lazy Child Data"), 1000)),
+  });
+};
+
+function DeferredChild() {
+  let data = useLoaderData();
+  return (
+    <div>
+      <p>{data.critical}</p>
+      <Deferred data={data.lazy} fallback={<p>loading child...</p>}>
+        <RenderDeferredData />
+      </Deferred>
+    </div>
+  );
+}
+
+function RenderDeferredData() {
+  let data = useDeferred();
+
+  if (isDeferredError(data)) {
+    return (
+      <p style={{ color: "red" }}>
+        Error! {data.message} {data.stack}
+      </p>
+    );
+  }
+
+  return <p>{data}</p>;
+}
+
+function RenderDeferredError() {
+  let error = useDeferred() as Error;
+  return (
+    <p style={{ color: "red" }}>
+      Error! {error.message} {error.stack}
+    </p>
+  );
+}
+
 function App() {
   return (
     <DataBrowserRouter fallbackElement={<Fallback />}>
       <Route path="/" element={<Layout />}>
         <Route index loader={homeLoader} element={<Home />} />
+        <Route
+          path="deferred"
+          loader={deferredLoader}
+          element={<DeferredPage />}
+        >
+          <Route
+            path="child"
+            loader={deferredChildLoader}
+            element={<DeferredChild />}
+          />
+        </Route>
+        <Route
+          path="long-load"
+          loader={() => sleep(3000)}
+          element={<h1>👋</h1>}
+        />
         <Route
           path="todos"
           action={todosAction}

package.json

@@ -100,13 +100,13 @@
   },
   "filesize": {
     "packages/router/dist/router.production.min.js": {
-      "none": "21 kB"
+      "none": "23 kB"
     },
     "packages/router/dist//umd/router.production.min.js": {
-      "none": "23 kB"
+      "none": "25 kB"
     },
     "packages/react-router/dist/react-router.production.min.js": {
-      "none": "10 kB"
+      "none": "11 kB"
     },
     "packages/react-router/dist/umd/react-router.production.min.js": {
       "none": "12 kB"

packages/react-router-dom/index.tsx

@@ -97,6 +97,7 @@ export type {
 } from "react-router";
 export {
   DataMemoryRouter,
+  Deferred,
   MemoryRouter,
   Navigate,
   NavigationType,
@@ -106,6 +107,8 @@ export {
   Routes,
   createPath,
   createRoutesFromChildren,
+  deferred,
+  isDeferredError,
   isRouteErrorResponse,
   generatePath,
   json,
@@ -116,6 +119,7 @@ export {
   renderMatches,
   resolvePath,
   useActionData,
+  useDeferred,
   useHref,
   useInRouterContext,
   useLoaderData,

packages/react-router-native/index.tsx

@@ -61,6 +61,7 @@ export type {
 } from "react-router";
 export {
   DataMemoryRouter,
+  Deferred,
   MemoryRouter,
   Navigate,
   NavigationType,
@@ -70,6 +71,8 @@ export {
   Routes,
   createPath,
   createRoutesFromChildren,
+  deferred,
+  isDeferredError,
   isRouteErrorResponse,
   generatePath,
   json,
@@ -80,6 +83,7 @@ export {
   renderMatches,
   resolvePath,
   useActionData,
+  useDeferred,
   useHref,
   useInRouterContext,
   useLoaderData,

packages/react-router/index.ts

@@ -22,7 +22,9 @@ import type {
 import {
   Action as NavigationType,
   createPath,
+  deferred,
   generatePath,
+  isDeferredError,
   isRouteErrorResponse,
   json,
   matchPath,
@@ -47,8 +49,9 @@ import type {
 import {
   createRoutesFromChildren,
   renderMatches,
-  MemoryRouter,
   DataMemoryRouter,
+  Deferred,
+  MemoryRouter,
   Navigate,
   Outlet,
   Route,
@@ -78,6 +81,7 @@ import {
   useResolvedPath,
   useRoutes,
   useActionData,
+  useDeferred,
   useLoaderData,
   useMatches,
   useRouteLoaderData,
@@ -131,6 +135,7 @@ export type {
 };
 export {
   DataMemoryRouter,
+  Deferred,
   MemoryRouter,
   Navigate,
   NavigationType,
@@ -140,6 +145,8 @@ export {
   Routes,
   createPath,
   createRoutesFromChildren,
+  deferred,
+  isDeferredError,
   isRouteErrorResponse,
   generatePath,
   json,
@@ -150,6 +157,7 @@ export {
   renderMatches,
   resolvePath,
   useActionData,
+  useDeferred,
   useHref,
   useInRouterContext,
   useLoaderData,