React Quickstart

Use this pre-built prompt to get started faster.

Before you start

Set up a Clerk application

Example repository

React Quickstart Repo

This tutorial will demonstrate how to create a new React app using Vite and add authentication to it using Clerk. If you would like to create an application using the React Router framework, see the React Router quickstart.

Create a new React app

If you don't already have a React app, run the following commands to create a new one using Vite.

npm

pnpm

yarn

bun

terminal

npm create vite@latest clerk-react -- --template react-ts
cd clerk-react
npm install

terminal

pnpm create vite clerk-react --template react-ts
cd clerk-react
pnpm install

terminal

yarn create vite clerk-react --template react-ts
cd clerk-react
yarn install

terminal

bunx create-vite clerk-react --template react-ts
cd clerk-react
bun install

Install `@clerk/clerk-react`

The Clerk React SDK gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

npm

pnpm

yarn

bun

terminal

npm install @clerk/clerk-react

terminal

pnpm add @clerk/clerk-react

terminal

yarn add @clerk/clerk-react

terminal

bun add @clerk/clerk-react

Set your Clerk API keys

.env

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 { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
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>
    <App />
  </StrictMode>,
)

Add `<ClerkProvider>` to your app

The <ClerkProvider> component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with <ClerkProvider> to make authentication globally accessible. See the reference docs for other configuration options.

Pass your Publishable Key as a prop to the component, as shown in the following example:

src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.tsx'
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 file')
}

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

Create a header with Clerk components

You can control which content signed-in and signed-out users can see with the prebuilt control components. The following example creates 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. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
<SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.

src/App.tsx

import './App.css'
import { SignedIn, SignedOut, SignInButton, SignUpButton, UserButton } from '@clerk/clerk-react'

function App() {
  return (
    <>
      <header>
        {/* Show the sign-in and sign-up buttons when the user is signed out */}
        <SignedOut>
          <SignInButton />
          <SignUpButton />
        </SignedOut>
        {/* Show the user button when the user is signed in */}
        <SignedIn>
          <UserButton />
        </SignedIn>
      </header>
    </>
  )
}

export default App

Run your project

Run your project with the following command:

npm

pnpm

yarn

bun

terminal

npm run dev

terminal

pnpm run dev

terminal

yarn dev

terminal

bun run dev

Create your first user

Visit your app's homepage at http://localhost:5173.
Select "Sign up" on the page and authenticate to create your first user.

Edit on GitHub

React Quickstart

Before you start

Example repository

Create a new React app

Install `@clerk/clerk-react`

Set your Clerk API keys

Import the Clerk Publishable Key

Add `<ClerkProvider>` to your app

Create a header with Clerk components

Run your project

Create your first user

Next steps

Declarative mode

Prebuilt components

Customization & localization

Client-side helpers (hooks)

React Quickstart

Before you start

Example repository

Feedback