feat(react-router): Introduce middleware and context

.changeset/quiet-bats-protect.md

@@ -0,0 +1,54 @@
+---
+'@clerk/react-router': major
+---
+
+Introduce [React Router middleware](https://reactrouter.com/how-to/middleware) support with `clerkMiddleware()` for improved performance and streaming capabilities.
+
+Usage of `rootAuthLoader` without the `clerkMiddleware()` installed is now deprecated and will be removed in the next major version.
+
+**Before (Deprecated - will be removed):**
+
+```tsx
+import { rootAuthLoader } from '@clerk/react-router/ssr.server'
+
+export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args)
+```
+
+**After (Recommended):**
+
+1. Enable the `v8_middleware` future flag:
+
+```ts
+// react-router.config.ts
+export default {
+  future: {
+    v8_middleware: true,
+  },
+} satisfies Config;
+```
+
+2. Use the middleware in your app:
+
+```tsx
+import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server'
+
+export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]
+
+export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args)
+```
+
+**Streaming Support (with middleware):**
+
+```tsx
+export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]
+
+export const loader = (args: Route.LoaderArgs) => {
+  const nonCriticalData = new Promise((res) =>
+    setTimeout(() => res('non-critical'), 5000),
+  )
+
+  return rootAuthLoader(args, () => ({
+    nonCriticalData
+  }))
+}
+```

integration/presets/utils.ts

@@ -2,7 +2,9 @@ import path from 'node:path';
 
 export function linkPackage(pkg: string) {
   // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (process.env.CI === 'true') return '*';
+  if (process.env.CI === 'true') {
+    return '*';
+  }
 
   return `link:${path.resolve(process.cwd(), `packages/${pkg}`)}`;
 }

integration/templates/react-router-library/package.json

@@ -9,15 +9,14 @@
     "preview": "vite preview --port $PORT"
   },
   "dependencies": {
-    "@clerk/react-router": "^0.1.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-router": "^7.1.2"
+    "react-router": "^7.9.1"
   },
   "devDependencies": {
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
-    "@vitejs/plugin-react": "^4.3.4",
+    "@vitejs/plugin-react": "^5.0.3",
     "globals": "^15.12.0",
     "typescript": "~5.7.3",
     "vite": "^6.0.1"

integration/templates/react-router-node/app/root.tsx

@@ -1,9 +1,11 @@
 import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
 import { rootAuthLoader } from '@clerk/react-router/ssr.server';
 import { ClerkProvider } from '@clerk/react-router';
-
 import type { Route } from './+types/root';
 
+// TODO: Uncomment when published
+// export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()];
+
 export async function loader(args: Route.LoaderArgs) {
   return rootAuthLoader(args);
 }

integration/templates/react-router-node/app/routes/protected.tsx

@@ -14,7 +14,8 @@ export async function loader(args: Route.LoaderArgs) {
   const user = await createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }).users.getUser(userId);
 
   return {
-    user,
+    firstName: user.firstName,
+    emailAddress: user.emailAddresses[0].emailAddress,
   };
 }
 
@@ -24,8 +25,8 @@ export default function Profile({ loaderData }: Route.ComponentProps) {
       <h1>Protected</h1>
       <UserProfile />
       <ul>
-        <li>First name: {loaderData.user.firstName}</li>
-        <li>Email: {loaderData.user.emailAddresses[0].emailAddress}</li>
+        <li>First name: {loaderData.firstName}</li>
+        <li>Email: {loaderData.emailAddress}</li>
       </ul>
     </div>
   );

integration/templates/react-router-node/package.json

@@ -9,21 +9,20 @@
     "typecheck": "react-router typegen && tsc --build --noEmit"
   },
   "dependencies": {
-    "@clerk/react-router": "latest",
-    "@react-router/node": "^7.1.2",
-    "@react-router/serve": "^7.1.2",
+    "@react-router/node": "^7.9.1",
+    "@react-router/serve": "^7.9.1",
     "isbot": "^5.1.17",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-router": "^7.1.2"
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router": "^7.9.1"
   },
   "devDependencies": {
-    "@react-router/dev": "^7.1.2",
+    "@react-router/dev": "^7.9.1",
     "@types/node": "^20",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
     "typescript": "^5.7.3",
-    "vite": "^5.4.11",
-    "vite-tsconfig-paths": "^5.1.2"
+    "vite": "^7.1.5",
+    "vite-tsconfig-paths": "^5.1.4"
   }
 }

integration/templates/react-router-node/react-router.config.ts

@@ -4,4 +4,8 @@ export default {
   // Config options...
   // Server-side render by default, to enable SPA mode set this to `false`
   ssr: true,
+  future: {
+    v8_middleware: true,
+    unstable_optimizeDeps: true,
+  },
 } satisfies Config;

integration/tests/react-router/basic.test.ts

@@ -5,7 +5,7 @@ import type { FakeUser } from '../../testUtils';
 import { createTestUtils, testAgainstRunningApps } from '../../testUtils';
 
 testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes], withPattern: ['react-router.node'] })(
-  'basic tests for @react-router',
+  'basic tests for @react-router with middleware',
   ({ app }) => {
     test.describe.configure({ mode: 'parallel' });
 

integration/tests/react-router/pre-middleware.test.ts

@@ -0,0 +1,169 @@
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import type { FakeUser } from '../../testUtils';
+import { createTestUtils } from '../../testUtils';
+
+test.describe('basic tests for @react-router without middleware', () => {
+  test.describe.configure({ mode: 'parallel' });
+  let app: Application;
+  let fakeUser: FakeUser;
+
+  test.beforeAll(async () => {
+    test.setTimeout(90_000); // Wait for app to be ready
+    app = await appConfigs.reactRouter.reactRouterNode
+      .clone()
+      .addFile(
+        `app/root.tsx`,
+        () => `import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
+import { rootAuthLoader } from '@clerk/react-router/ssr.server';
+import { ClerkProvider } from '@clerk/react-router';
+
+import type { Route } from './+types/root';
+
+export async function loader(args: Route.LoaderArgs) {
+  return rootAuthLoader(args);
+}
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang='en'>
+      <head>
+        <meta charSet='utf-8' />
+        <meta
+          name='viewport'
+          content='width=device-width, initial-scale=1'
+        />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App({ loaderData }: Route.ComponentProps) {
+  return (
+    <ClerkProvider loaderData={loaderData}>
+      <main>
+        <Outlet />
+      </main>
+    </ClerkProvider>
+  );
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  let message = 'Oops!';
+  let details = 'An unexpected error occurred.';
+  let stack: string | undefined;
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? '404' : 'Error';
+    details = error.status === 404 ? 'The requested page could not be found.' : error.statusText || details;
+  } else if (import.meta.env.DEV && error && error instanceof Error) {
+    details = error.message;
+    stack = error.stack;
+  }
+
+  return (
+    <main>
+      <h1>{message}</h1>
+      <p>{details}</p>
+      {stack && (
+        <pre>
+          <code>{stack}</code>
+        </pre>
+      )}
+    </main>
+  );
+}
+`,
+      )
+      .commit();
+
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withEmailCodes);
+    await app.dev();
+
+    const u = createTestUtils({ app });
+    fakeUser = u.services.users.createFakeUser({
+      fictionalEmail: true,
+      withPhoneNumber: true,
+      withUsername: true,
+    });
+    await u.services.users.createBapiUser(fakeUser);
+  });
+
+  test.afterAll(async () => {
+    await fakeUser.deleteIfExists();
+    await app.teardown();
+  });
+
+  test.afterEach(async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.page.signOut();
+    await u.page.context().clearCookies();
+  });
+
+  test('can sign in and user button renders', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.po.signIn.goTo();
+
+    await u.po.signIn.setIdentifier(fakeUser.email);
+    await u.po.signIn.setPassword(fakeUser.password);
+    await u.po.signIn.continue();
+    await u.po.expect.toBeSignedIn();
+
+    await u.page.waitForAppUrl('/');
+
+    await u.po.userButton.waitForMounted();
+    await u.po.userButton.toggleTrigger();
+    await u.po.userButton.waitForPopover();
+
+    await u.po.userButton.toHaveVisibleMenuItems([/Manage account/i, /Sign out$/i]);
+  });
+
+  test('redirects to sign-in when unauthenticated', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+
+    await u.page.goToRelative('/protected');
+    await u.page.waitForURL(`${app.serverUrl}/sign-in`);
+    await u.po.signIn.waitForMounted();
+  });
+
+  test('renders control components contents', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+
+    await u.page.goToAppHome();
+    await expect(u.page.getByText('SignedOut')).toBeVisible();
+
+    await u.page.goToRelative('/sign-in');
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+    await u.po.expect.toBeSignedIn();
+    await expect(u.page.getByText('SignedIn')).toBeVisible();
+  });
+
+  test('renders user profile with SSR data', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+
+    await u.page.goToRelative('/sign-in');
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+    await u.po.expect.toBeSignedIn();
+
+    await u.po.userButton.waitForMounted();
+    await u.page.goToRelative('/protected');
+    await u.po.userProfile.waitForMounted();
+
+    // Fetched from an API endpoint (/api/me), which is server-rendered.
+    // This also verifies that the server middleware is working.
+    await expect(u.page.getByText(`First name: ${fakeUser.firstName}`)).toBeVisible();
+    await expect(u.page.getByText(`Email: ${fakeUser.email}`)).toBeVisible();
+  });
+});

package.json

@@ -47,7 +47,7 @@
     "test:integration:nextjs": "E2E_APP_ID=next.appRouter.* pnpm test:integration:base --grep @nextjs",
     "test:integration:nuxt": "E2E_APP_ID=nuxt.node npm run test:integration:base -- --grep @nuxt",
     "test:integration:quickstart": "E2E_APP_ID=quickstart.* pnpm test:integration:base --grep @quickstart",
-    "test:integration:react-router": "E2E_APP_ID=react-router.* npm run test:integration:base -- --grep @react-router",
+    "test:integration:react-router": "E2E_APP_ID=react-router.* pnpm test:integration:base --grep @react-router",
     "test:integration:sessions": "DISABLE_WEB_SECURITY=true pnpm test:integration:base --grep @sessions",
     "test:integration:tanstack-react-router": "E2E_APP_ID=tanstack.react-router pnpm test:integration:base --grep @tanstack-react-router",
     "test:integration:tanstack-react-start": "E2E_APP_ID=tanstack.react-start pnpm test:integration:base --grep @tanstack-react-start",

packages/react-router/package.json

@@ -30,6 +30,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
     "./ssr.server": {
       "types": "./dist/ssr/index.d.ts",
       "default": "./dist/ssr/index.js"
@@ -55,6 +59,9 @@
         "dist/*.d.ts",
         "dist/index.d.ts"
       ],
+      "server": [
+        "dist/server/index.d.ts"
+      ],
       "ssr.server": [
         "dist/ssr/index.d.ts"
       ],
@@ -92,12 +99,12 @@
   "devDependencies": {
     "@types/cookie": "^0.6.0",
     "esbuild-plugin-file-path-extensions": "^2.1.4",
-    "react-router": "7.8.2"
+    "react-router": "7.9.1"
   },
   "peerDependencies": {
     "react": "catalog:peer-react",
     "react-dom": "catalog:peer-react",
-    "react-router": "^7.1.2"
+    "react-router": "^7.9.0"
   },
   "engines": {
     "node": ">=20.0.0"