Skip to main content
Docs

Add React Router to your Clerk + React application

Before you start

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 .

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

Install react-router and @clerk/react-router

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

terminal
npm install react-router @clerk/react-router
terminal
yarn add react-router @clerk/react-router
terminal
pnpm 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 library 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>,
)

Set up React Router

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

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on