Docs

React Quickstart

You will learn the following:

  • Create a new React app using Vite
  • Install @clerk/clerk-react
  • Set your Clerk API keys
  • Add <ClerkProvider />
  • Create a header with Clerk components for users to sign in and out

Before you start

Example repository

Create a React app using Vite

Create a new React app using Vite by running the following command:

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 to make user authentication easier.

Add the SDK to your project by running the following command:

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

Set your Clerk API keys

.env.local
VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Import the Clerk publishable key

In your main.tsx file, import your Clerk publishable key. You can add an if statement to check that it is imported and that it exists. This will prevent running the app 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('Add your Clerk publishable key to the .env.local file')
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Add <ClerkProvider> to your app

The <ClerkProvider> component wraps your app to provide active session and user context to Clerk's hooks and other components. 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('Add your Clerk publishable key to the .env.local file')
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
      <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 control components. Create a header using the following components:

  • <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 />: 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 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>
  )
}

Create your first user

Run your project with the following command:

terminal
npm run dev
terminal
yarn dev
terminal
pnpm dev

Visit your app's homepage at http://localhost:5173. Sign up to create your first user.

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 (also known as Data Router), see the dedicated guide.

More resources

Learn more about Clerk components, how to customize them, and how to use Clerk's client-side helpers using the following guides.

Prebuilt components

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

Customization & localization

Learn how to customize and localize Clerk components.

Client-side helpers (hooks)

Learn more about Clerk's client-side helpers and how to use them.

Feedback

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

Last updated on