feat(rsc): add support for throwing redirect Response's at RSC render time

Author: jacob-ebey

.changeset/early-doors-obey.md

@@ -0,0 +1,6 @@
+---
+"@react-router/dev": minor
+"react-router": minor
+---
+
+add support for throwing redirect Response's at RSC render time

integration/helpers/rsc-parcel/src/prerender.tsx

@@ -20,12 +20,13 @@ export async function prerender(
     // Provide the React Server touchpoints.
     createFromReadableStream,
     // Render the router to HTML.
-    async renderHTML(getPayload) {
+    async renderHTML(getPayload, options) {
       const payload = getPayload();
 
       return await renderHTMLToReadableStream(
         <RSCStaticRouter getPayload={getPayload} />,
         {
+          ...options,
           bootstrapScriptContent,
           formState: await payload.formState,
         },

integration/helpers/rsc-vite/src/entry.ssr.tsx

@@ -16,12 +16,13 @@ export default async function handler(
     request,
     fetchServer,
     createFromReadableStream,
-    async renderHTML(getPayload) {
+    async renderHTML(getPayload, options) {
       const payload = getPayload();
 
       return ReactDomServer.renderToReadableStream(
         <RSCStaticRouter getPayload={getPayload} />,
         {
+          ...options,
           bootstrapScriptContent,
           signal: request.signal,
           formState: await payload.formState,

integration/rsc/rsc-test.ts

@@ -534,7 +534,12 @@ implementations.forEach((implementation) => {
                       id: "action-transition-state",
                       path: "action-transition-state",
                       lazy: () => import("./routes/action-transition-state/home"),
-                    }
+                    },
+                    {
+                      id: "render-redirect",
+                      path: "/render-redirect/:id?",
+                      lazy: () => import("./routes/render-redirect/home"),
+                    },
                   ],
                 },
               ] satisfies RSCRouteConfig;
@@ -1460,6 +1465,23 @@ implementations.forEach((implementation) => {
                 );
               }
             `,
+
+            "src/routes/render-redirect/home.tsx": js`
+              import { Link, redirect } from "react-router";
+
+              export default function RenderRedirect({ params: { id } }) {
+                if (id === "redirect") {
+                  throw redirect("/render-redirect/redirected");
+                }
+
+                return (
+                  <>
+                    <h1>{id || "home"}</h1>
+                    <Link to="/render-redirect/redirect">Redirect</Link>
+                  </>
+                )
+              }
+            `,
           },
         });
       });
@@ -1738,6 +1760,14 @@ implementations.forEach((implementation) => {
             "An error occurred in the Server Components render.",
           );
         });
+
+        test.only("Suppport throwing redirect Response from render", async ({
+          page,
+        }) => {
+          await page.goto(`http://localhost:${port}/render-redirect`);
+          await page.click("a");
+          await expect(page.getByText("redirected")).toBeAttached();
+        });
       });
 
       test.describe("Server Actions", () => {

packages/react-router-dev/config/default-rsc-entries/entry.ssr.tsx

@@ -17,12 +17,13 @@ export default async function handler(
     request,
     fetchServer,
     createFromReadableStream,
-    async renderHTML(getPayload) {
+    async renderHTML(getPayload, options) {
       const payload = getPayload();
 
       return ReactDomServer.renderToReadableStream(
         <RSCStaticRouter getPayload={getPayload} />,
         {
+          ...options,
           bootstrapScriptContent,
           signal: request.signal,
           formState: await payload.formState,

packages/react-router/lib/components.tsx

@@ -400,6 +400,12 @@ export interface RouterProviderProps {
    * For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).
    */
   unstable_useTransitions?: boolean;
+
+  /**
+   * Control whether rsc specific behaviors are enabled. This includes
+   * `unstable_useTransitions` and redirects thrown at render time.
+   */
+  unstable_rsc?: boolean;
 }
 
 /**
@@ -432,14 +438,18 @@ export interface RouterProviderProps {
  * @param {RouterProviderProps.unstable_onError} props.unstable_onError n/a
  * @param {RouterProviderProps.router} props.router n/a
  * @param {RouterProviderProps.unstable_useTransitions} props.unstable_useTransitions n/a
+ * @param {RouterProviderProps.unstable_rsc} props.unstable_rsc n/a
  * @returns React element for the rendered router
  */
 export function RouterProvider({
   router,
   flushSync: reactDomFlushSyncImpl,
   unstable_onError,
   unstable_useTransitions,
+  unstable_rsc,
 }: RouterProviderProps): React.ReactElement {
+  unstable_useTransitions = unstable_useTransitions || unstable_rsc;
+
   let [_state, setStateImpl] = React.useState(router.state);
   let [state, setOptimisticState] = useOptimisticSafe(_state);
   let [pendingState, setPendingState] = React.useState<RouterState>();
@@ -718,6 +728,7 @@ export function RouterProvider({
                   future={router.future}
                   state={state}
                   unstable_onError={unstable_onError}
+                  unstable_rsc={unstable_rsc}
                 />
               </Router>
             </ViewTransitionContext.Provider>
@@ -764,13 +775,22 @@ function DataRoutes({
   future,
   state,
   unstable_onError,
+  unstable_rsc,
 }: {
   routes: DataRouteObject[];
   future: DataRouter["future"];
   state: RouterState;
   unstable_onError: unstable_ClientOnErrorFunction | undefined;
+  unstable_rsc: boolean | undefined;
 }): React.ReactElement | null {
-  return useRoutesImpl(routes, undefined, state, unstable_onError, future);
+  return useRoutesImpl(
+    routes,
+    undefined,
+    state,
+    unstable_onError,
+    unstable_rsc,
+    future,
+  );
 }
 
 /**

packages/react-router/lib/dom-export/hydrated-router.tsx

@@ -80,9 +80,11 @@ function initSsrInfo(): void {
 function createHydratedRouter({
   getContext,
   unstable_instrumentations,
+  unstable_rsc,
 }: {
   getContext?: RouterInit["getContext"];
   unstable_instrumentations?: unstable_ClientInstrumentation[];
+  unstable_rsc?: boolean;
 }): DataRouter {
   initSsrInfo();
 
@@ -178,7 +180,7 @@ function createHydratedRouter({
     unstable_instrumentations,
     mapRouteProperties,
     future: {
-      middleware: ssrInfo.context.future.v8_middleware,
+      unstable_rsc,
     },
     dataStrategy: getTurboStreamSingleFetchDataStrategy(
       () => router,
@@ -317,6 +319,13 @@ export interface HydratedRouterProps {
    * For more information, please see the [docs](https://reactrouter.com/explanation/react-transitions).
    */
   unstable_useTransitions?: boolean;
+
+  /**
+   * Control whether RSC specific behaviors are introduced. This currently
+   * enables the unstable_useTransitions flag, as well as the ability to handle
+   * thrown redirect responses during the render phase.
+   */
+  unstable_rsc?: boolean;
 }
 
 /**
@@ -336,6 +345,7 @@ export function HydratedRouter(props: HydratedRouterProps) {
     router = createHydratedRouter({
       getContext: props.getContext,
       unstable_instrumentations: props.unstable_instrumentations,
+      unstable_rsc: props.unstable_rsc,
     });
   }
 

packages/react-router/lib/dom/server.tsx

@@ -232,12 +232,21 @@ function DataRoutes({
   routes,
   future,
   state,
+  unstable_rsc,
 }: {
   routes: DataRouteObject[];
   future: DataRouter["future"];
   state: RouterState;
+  unstable_rsc?: boolean;
 }): React.ReactElement | null {
-  return useRoutesImpl(routes, undefined, state, undefined, future);
+  return useRoutesImpl(
+    routes,
+    undefined,
+    state,
+    undefined,
+    unstable_rsc,
+    future,
+  );
 }
 
 function serializeErrors(

packages/react-router/lib/errors.ts

@@ -0,0 +1,29 @@
+const ERROR_DIGEST_BASE = "REACT_ROUTER_ERROR";
+const ERROR_DIGEST_REDIRECT = "REDIRECT";
+
+export function createRedirectErrorDigest(response: Response) {
+  return `${ERROR_DIGEST_BASE}:${ERROR_DIGEST_REDIRECT}:${JSON.stringify({
+    status: response.status,
+    location: response.headers.get("Location"),
+  })}`;
+}
+
+export function decodeRedirectErrorDigest(
+  digest: string,
+): undefined | { status: number; location: string } {
+  if (digest.startsWith(`${ERROR_DIGEST_BASE}:${ERROR_DIGEST_REDIRECT}:{`)) {
+    try {
+      let parsed = JSON.parse(digest.slice(28));
+      if (
+        typeof parsed === "object" &&
+        parsed &&
+        "status" in parsed &&
+        typeof parsed.status === "number" &&
+        "location" in parsed &&
+        typeof parsed.location === "string"
+      ) {
+        return parsed;
+      }
+    } catch {}
+  }
+}

packages/react-router/lib/hooks.tsx

@@ -58,6 +58,7 @@ import type {
 } from "./types/route-data";
 import type { unstable_ClientOnErrorFunction } from "./components";
 import type { RouteModules } from "./types/register";
+import { decodeRedirectErrorDigest } from "./errors";
 
 /**
  * Resolves a URL against the current {@link Location}.
@@ -758,6 +759,7 @@ export function useRoutesImpl(
   locationArg?: Partial<Location> | string,
   dataRouterState?: DataRouter["state"],
   unstable_onError?: unstable_ClientOnErrorFunction,
+  unstable_rsc?: boolean,
   future?: DataRouter["future"],
 ): React.ReactElement | null {
   invariant(
@@ -912,6 +914,7 @@ export function useRoutesImpl(
     parentMatches,
     dataRouterState,
     unstable_onError,
+    unstable_rsc,
     future,
   );
 
@@ -991,6 +994,7 @@ type RenderErrorBoundaryProps = React.PropsWithChildren<{
   component: React.ReactNode;
   routeContext: RouteContextObject;
   onError?: (error: unknown, errorInfo?: React.ErrorInfo) => void;
+  unstable_rsc?: boolean;
 }>;
 
 type RenderErrorBoundaryState = {
@@ -1062,17 +1066,56 @@ export class RenderErrorBoundary extends React.Component<
   }
 
   render() {
-    return this.state.error !== undefined ? (
-      <RouteContext.Provider value={this.props.routeContext}>
-        <RouteErrorContext.Provider
-          value={this.state.error}
-          children={this.props.component}
-        />
-      </RouteContext.Provider>
-    ) : (
-      this.props.children
-    );
+    let result =
+      this.state.error !== undefined ? (
+        <RouteContext.Provider value={this.props.routeContext}>
+          <RouteErrorContext.Provider
+            value={this.state.error}
+            children={this.props.component}
+          />
+        </RouteContext.Provider>
+      ) : (
+        this.props.children
+      );
+
+    if (this.props.unstable_rsc) {
+      return (
+        <RSCErrorHandler error={this.state.error}>{result}</RSCErrorHandler>
+      );
+    }
+
+    return result;
+  }
+}
+
+const errorRedirectPromises = new WeakMap<any, Promise<void>>();
+function RSCErrorHandler({
+  children,
+  error,
+}: {
+  children: React.ReactNode;
+  error: unknown;
+}) {
+  if (
+    typeof error === "object" &&
+    error &&
+    "digest" in error &&
+    typeof error.digest === "string"
+  ) {
+    let redirect = decodeRedirectErrorDigest(error.digest);
+    if (redirect) {
+      let promise = errorRedirectPromises.get(error);
+      if (!promise) {
+        // TODO: Handle external redirects?
+        promise = window.__reactRouterDataRouter!.navigate(redirect.location, {
+          replace: true,
+        });
+        errorRedirectPromises.set(error, promise);
+      }
+      throw promise;
+    }
   }
+  return children;
 }
 
 interface RenderedRouteProps {
@@ -1107,6 +1150,7 @@ export function _renderMatches(
   parentMatches: RouteMatch[] = [],
   dataRouterState: DataRouter["state"] | null = null,
   unstable_onError: unstable_ClientOnErrorFunction | null = null,
+  unstable_rsc: boolean | undefined = undefined,
   future: DataRouter["future"] | null = null,
 ): React.ReactElement | null {
   if (matches == null) {
@@ -1275,6 +1319,7 @@ export function _renderMatches(
           error={error}
           children={getChildren()}
           routeContext={{ outlet: null, matches, isDataRoute: true }}
+          unstable_rsc={unstable_rsc}
           onError={onError}
         />
       ) : (