Add React Router to your Clerk + React application

Install react-router and @clerk/react-router
Set your Clerk API keys
Update <ClerkProvider>
Set up React Router
Next steps

Before you start

Set up a React + Clerk application

React Router supports three different routing strategies, or "modes":

Declarative mode: Enables basic routing features like matching URLs to components, navigating around the app, and providing active states with APIs like <Link>, useNavigate(), and useLocation().
Data mode: Adds data loading, actions, pending states and more with APIs like loader, action, and useFetcher. To use React Router in data mode, see the demo repository. A guide is coming soon.
Framework mode: Use React Router as a framework to build your entire app. To use React Router as a framework instead, see the React Router quickstart.

This guide will cover how to add React Router in declarative mode, assuming you have followed the React quickstart.

Install `react-router` and `@clerk/react-router`

Run the following command to install both React Router and the Clerk React Router SDK:

npm

pnpm

yarn

bun

terminal

npm install react-router @clerk/react-router

terminal

pnpm add react-router @clerk/react-router

terminal

yarn add react-router @clerk/react-router

terminal

bun add react-router @clerk/react-router

Set your Clerk API keys

Note

You will not need the Clerk Secret Key in React Router's declarative mode, as it should never be used on the client-side.

.env

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Update `<ClerkProvider>`

Update <ClerkProvider> to be imported from @clerk/react-router instead of @clerk/clerk-react.

src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ClerkProvider } from '@clerk/react-router'
import './index.css'
import App from './App.tsx'

// Import your Publishable Key
const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

if (!PUBLISHABLE_KEY) {
  throw new Error('Add your Clerk Publishable Key to the .env file')
}

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
      <App />
    </ClerkProvider>
  </StrictMode>,
)

To use declarative mode, wrap your app in a <BrowserRouter>. To define your app's routes, add <Routes> and <Route> components. This example adds the / (home) route and renders the <App /> component when the URL matches. Read more about routing in the React Router docs.

src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter, Routes, Route } from 'react-router'
import { ClerkProvider } from '@clerk/react-router'
import './index.css'
import App from './App.tsx'

// Import your Publishable Key
const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

if (!PUBLISHABLE_KEY) {
  throw new Error('Add your Clerk Publishable Key to the .env file')
}

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BrowserRouter>
      <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
        <Routes>
          <Route path="/" element={<App />} />
        </Routes>
      </ClerkProvider>
    </BrowserRouter>
  </StrictMode>,
)