Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com
react's logo

Add authentication and user management to your React app with Clerk

You will learn how to:

    • Create a new React application using Vite
    • Install @clerk/clerk-react
    • Set up your environment keys
    • Import the Publishable Key
    • Wrap your React app in <ClerkProvider />
    • Use Clerk components to protect your content
    • Embed the <SignInButton /> and <SignOutButton />
    • Deploy your application
Example repository

Set up a React application using Vite

Scaffold your new React application using Vite(opens in a new tab).

terminal
npm create vite@latest clerk-react -- --template react-ts cd clerk-react npm install npm run dev
terminal
yarn create vite clerk-react--template react-ts cd clerk-react yarn install yarn dev
terminal
pnpm create vite clerk-react --template react-ts cd clerk-react pnpm install pnpm dev

Install @clerk/clerk-react

Clerk's React SDK gives you access to prebuilt components, hooks, and helpers for React. Install it by running the following command in your terminal:

terminal
npm install @clerk/clerk-react
terminal
yarn add @clerk/clerk-react
terminal
pnpm add @clerk/clerk-react

Set environment keys

In your React project's root folder, create a .env.local file alongside package.json and other configuration files.

Add the following code to your .env.local file to set your public key.

Pro tip! If you are signed into your Clerk Dashboard, you can copy your publishable key below. Otherwise, you can find it in the Clerk Dashboard on the API Keys(opens in a new tab) page.

.env.local
VITE_CLERK_PUBLISHABLE_KEY={{pub_key}}

Import the Publishable Key

You will need to import your Publishable Key into your application. You can add an if statement to check that it is imported and that it exists. This will prevent running the application without the Publishable Key, and will also prevent TypeScript errors.

src/main.tsx
import React from 'react' import ReactDOM from 'react-dom/client' import App from './App.tsx' import './index.css' // Import your publishable key const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY if (!PUBLISHABLE_KEY) { throw new Error("Missing Publishable Key") } ReactDOM.createRoot(document.getElementById('root')!).render( <React.StrictMode> <App /> </React.StrictMode>, )

Wrap your app in <ClerkProvider />

The <ClerkProvider /> component provides active session and user context to Clerk's hooks and other components. Import it into your app by adding import { ClerkProvider } from '@clerk/clerk-react' at the top of your /src/main.tsx file.

src/main.tsx
import React from 'react' import ReactDOM from 'react-dom/client' import App from './App.tsx' import './index.css' import { ClerkProvider } from '@clerk/clerk-react' // Import your publishable key const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY if (!PUBLISHABLE_KEY) { throw new Error("Missing Publishable Key") } ReactDOM.createRoot(document.getElementById('root')!).render( <React.StrictMode> <ClerkProvider publishableKey={PUBLISHABLE_KEY}> <App /> </ClerkProvider> </React.StrictMode>, )

Use Clerk components to protect your content

Clerk offers a set of prebuilt components that can gate access to content based on whether a user is signed in and has the correct permissions. You can use Clerk's <SignedIn> and <SignedOut> components to restrict access to content and even whole pages. The <SignedIn> component requires the user be signed in to view the content inside the tags. The <SignedOut> components requires the user to be signed out.

src/App.tsx
import { SignedOut, SignedIn } from "@clerk/clerk-react" function App() { return ( <div> <SignedOut> <p>This content is public. Only signed out users can see this.</p> </SignedOut> <SignedIn> <p>This content is private. Only signed in users can see this.</p> </SignedIn> </div> ) } export default App

Start your React application via npm run dev and visit http://localhost:5173 to see what signed out users will see. Next you will add a button so you can sign in.

Embed the <SignInButton /> and <SignOutButton />

The <SignInButton /> and <SignOutButton /> are components that you can use to either create a basic button or to wrap around your styled button and turn it into a sign-in or sign-out button.

Add a <SignInButton /> inside the content wrapped by <SignedOut> so people have an option to sign in. And add a <SignOutButton /> inside the content wrapped by <SignedIn> to let users who are signed in sign out.

Notice the signOutCallback prop being passed to <SignOutButton />. The signOutCallback prop lets you customize the behaviour of your app after sign out. In this example, the user is redirected to the homepage (/) of the application. Replace the redirect function with the one respective one of your router.

src/App.tsx
import { SignOutButton, SignInButton, SignedIn, SignedOut } from "@clerk/clerk-react" function App() { return ( <div> <SignedOut> <SignInButton /> <p>This content is public. Only signed out users can see the SignInButton above this text.</p> </SignedOut> <SignedIn> <SignOutButton signOutCallback={() => redirect('/')} /> <p>This content is private. Only signed in users can see the SignOutButton above this text.</p> </SignedIn> </div> ) } export default App

Visit http://localhost:5173 and try signing in to see the protected content and signing out to see the protected and unprotected content.

Deploy your application

You're ready to deploy your app to production and welcome new users!

You're authenticated!

Congratulations! Your app is now using Clerk to authenticate users. But this is just the first step. If you would like to clone or investigate this application, please check out:

Next step: Add routing with React Router

React has many options for handling routing, and you are free to choose the option that suits you best. If you would like to learn how to integrate React Router's latest Data API-based router (nicknamed Data Router), please see the Add React Router to your Clerk Powered application guide.

You can also learn more about Clerk components, how to customize them, and how to use Clerk's client side helpers. The following guides are good places to start.

Add React Router

Learn how to add routing to your app with React Router.

Learn More

Customization & Localization

Learn how to customize and localize the Clerk components.

Learn More

Authentication Components

Learn more about all our authentication components.

Learn More

Client Side Helpers

Learn more about our client side helpers and how to use them.

Learn More

Last updated on February 13, 2024

What did you think of this content?

Clerk © 2024