Skip to Content
You are viewing a beta version of Clerk Docs
Visit the latest docs
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

React Quickstart

You will learn how to:

    • Create a new React application using Vite
    • Install @clerk/clerk-react
    • Set up your environment variables
    • Import the Clerk publishable key
    • Add <ClerkProvider /> to your application
    • Create a header with Clerk components for users to sign in and out
Example repository

You're reading the quickstart guide for the beta of the next major version of the React SDK. For more information about the changes from the current version, check out the upgrade guide!

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@beta -- --template react-ts cd clerk-react npm install npm run dev
terminal
yarn create vite clerk-react@beta --template react-ts cd clerk-react yarn install yarn dev
terminal
pnpm create vite clerk-react@beta --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.

To get started using Clerk with React, add the SDK to your project:

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

Set your environment variables

  1. If you don't have an .env.local file in the root directory of your React project, create one now.
  2. Find your Clerk publishable key. If you're signed into Clerk, the .env.local snippet below will contain your key. Otherwise:
  1. Add your key to your .env.local file.

The final result should look as follows:

.env.local
VITE_CLERK_PUBLISHABLE_KEY={{pub_key}}

Import the Clerk publishable key

You will need to import your Clerk 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>, )

Add <ClerkProvider> to your app

All Clerk hooks and components must be children of the <ClerkProvider> component, which provides active session and user context.

To make this data available across your entire app, wrap your app in the <ClerkProvider> component. You must pass your publishable key as a prop to the <ClerkProvider> component.

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

Create a header with Clerk components

You can control which content signed in and signed out users can see with Clerk's prebuilt components. To get started, create a header for your users to sign in or out. To do this, you will use:

  • <SignedIn>: Children of this component can only be seen while signed in.
  • <SignedOut>: Children of this component can only be seen while signed out.
  • <UserButton />: A prebuilt component that comes styled out of the box to show the avatar from the account the user is signed in with.
  • <SignInButton />: An unstyled component that links to the sign-in page or displays the sign-in modal.
src/App.tsx
import { SignedIn, SignedOut, SignInButton, UserButton } from "@clerk/clerk-react"; export default function App() { return ( <header> <SignedOut> <SignInButton /> </SignedOut> <SignedIn> <UserButton /> </SignedIn> </header> ) }

Then, visit your app's homepage at http://localhost:5173 while signed out to see the sign-in button. Once signed in, your app will render the user button.

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.

More resources

You can also learn more about Clerk components, how to customize them, and how to use Clerk's client side helpers. The following guides will help you get started.

Prebuilt Components

Learn more about Clerk's suite of components that let you quickly add authentication to your app.

Learn More

Customization & Localization

Learn how to customize and localize Clerk components.

Learn More

Client Side Helpers

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

Learn More

Last updated on March 12, 2024

What did you think of this content?

Clerk © 2024