React Router Quickstart

Example repository

React Router Quickstart Repo

React Router can be used in different modes: declarative, data, or framework. This tutorial explains how to use React Router in framework mode. To use React Router in declarative mode instead, see the dedicated guide.

This tutorial assumes that you're using React Router v7.1.2 or later in framework mode.

Create a new React app using React Router

If you don't already have a React app using React Router, run the following commands to create a new one.

npm

pnpm

yarn

bun

npm create react-router@latest clerk-react-router
cd clerk-react-router

pnpm create react-router clerk-react-router
cd clerk-react-router

yarn create react-router clerk-react-router
cd clerk-react-router

bunx create-react-router clerk-react-router
cd clerk-react-router

Install `@clerk/react-router`

The Clerk React Router SDK gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

npm

pnpm

yarn

bun

npm install @clerk/react-router

pnpm add @clerk/react-router

yarn add @clerk/react-router

bun add @clerk/react-router

Important

While an upstream issue is being fixed, you must add @clerk/react-router to the ssr.noExternal array in your vite.config.ts file. Without it, every page fails during server-side rendering in development with Error: useNavigate() may be used only in the context of a <Router> component. — even though npm ls react-router shows a single installed copy.

vite.config.ts

export default defineConfig({
  // ...
  ssr: {
    noExternal: ['@clerk/react-router'],
  },
})

Set your Clerk API keys

Add the following keys to your .env file. These keys can always be retrieved from the API keys page in the Clerk Dashboard.

.env

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Add `clerkMiddleware()` and `rootAuthLoader()` to your app

clerkMiddleware() grants you access to user authentication state throughout your app. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

Important

If you're using React Router v7, enable the v8_middleware future flag in your react-router.config.ts file.

react-router.config.ts

import type { Config } from '@react-router/dev/config'

export default {
  // ...
  future: {
    v8_middleware: true,
  },
} satisfies Config

Add the following code to your root.tsx file to configure the clerkMiddleware() and rootAuthLoader() functions.

app/root.tsx

3 lines collapsed
import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router'
import type { Route } from './+types/root'
import stylesheet from './app.css?url'
import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server'

export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]

export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args)

62 lines collapsed
export const links: Route.LinksFunction = () => [
  { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
  {
    rel: 'preconnect',
    href: 'https://fonts.gstatic.com',
    crossOrigin: 'anonymous',
  },
  {
    rel: 'stylesheet',
    href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
  },
  { rel: 'stylesheet', href: stylesheet },
]

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() {
  return <Outlet />
}

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 className="pt-16 p-4 container mx-auto">
      <h1>{message}</h1>
      <p>{details}</p>
      {stack && (
        <pre className="w-full p-4 overflow-x-auto">
          <code>{stack}</code>
        </pre>
      )}
    </main>
  )
}

By default, clerkMiddleware() will not protect any routes. All routes are public and you must opt-in to protection for routes. See the clerkMiddleware() reference to learn how to require authentication for specific routes.

Add `<ClerkProvider>` and Clerk components to your app

The <ClerkProvider> component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with <ClerkProvider> to make authentication globally accessible. See the reference docs for other configuration options.

Copy and paste the following code into your root.tsx file. This:

Adds the <ClerkProvider> to your app, providing Clerk's authentication context to your app. Pass loaderData to the provider so it can access the authentication data loaded by rootAuthLoader().
Creates a header with Clerk's prebuilt components to allow users to sign in and out, and display different content for signed-in and signed-out users.

app/root.tsx

import { ClerkProvider, SignInButton, SignUpButton, Show, UserButton } from '@clerk/react-router'
import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router'
import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server'
39 lines collapsed

import type { Route } from './+types/root'
import stylesheet from './app.css?url'

export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]

export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args)

export const links: Route.LinksFunction = () => [
  { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
  {
    rel: 'preconnect',
    href: 'https://fonts.gstatic.com',
    crossOrigin: 'anonymous',
  },
  {
    rel: 'stylesheet',
    href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
  },
  { rel: 'stylesheet', href: stylesheet },
]

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>
  )
}

// Pull in the `loaderData` from the `rootAuthLoader()` function
export default function App({ loaderData }: Route.ComponentProps) {
  return (
    // Pass the `loaderData` to the `<ClerkProvider>` component
    <ClerkProvider loaderData={loaderData}>
      <header className="flex items-center justify-center py-8 px-4">
        <Show when="signed-out">
          <SignInButton />
          <SignUpButton />
        </Show>
        <Show when="signed-in">
          <UserButton />
        </Show>
      </header>
      <Outlet />
    </ClerkProvider>
  )
}
26 lines collapsed

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 className="pt-16 p-4 container mx-auto">
      <h1>{message}</h1>
      <p>{details}</p>
      {stack && (
        <pre className="w-full p-4 overflow-x-auto">
          <code>{stack}</code>
        </pre>
      )}
    </main>
  )
}

This example uses the following components:

<Show when="signed-in">: Children of this component can only be seen while signed in.
<Show when="signed-out">: Children of this component can only be seen while signed out.
<UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
<SignInButton />: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
<SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.

Run your project

Run your project with the following command:

npm

pnpm

yarn

bun

npm run dev

pnpm run dev

yarn dev

bun run dev

Create your first user

Visit your app's homepage at http://localhost:5173.
Select "Sign up" on the page and authenticate to create your first user.

Organizations - Organizations are shared accounts that let teams collaborate, manage members and roles, and control access to shared resources.
Billing - Billing enables you to manage subscriptions, free trials, payments, plans, and billing-related webhook events for B2C and B2B applications.
Waitlist - Waitlist lets you collect signups and control access to new products or features before launch through a simple, integrated workflow.

Last updated on Jul 23, 2026

Edit on GitHub

React Router Quickstart

Example repository

Create a new React app using React Router

Install `@clerk/react-router`

Set your Clerk API keys

Add `clerkMiddleware()` and `rootAuthLoader()` to your app

Add `<ClerkProvider>` and Clerk components to your app

Run your project

Create your first user

Next steps

Prebuilt components

Build custom flows

Read user data

Customization & localization

More to explore

React Router Quickstart

Example repository

Feedback