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
Create a React app using Vite
Run the following commands to create a new React app using Vite:
npm create vite@latest clerk-react -- --template react-ts
cd clerk-react
npm install
npm run devyarn create vite clerk-react --template react-ts
cd clerk-react
yarn install
yarn devpnpm create vite clerk-react --template react-ts
cd clerk-react
pnpm install
pnpm devbun create vite clerk-react --template react-ts
cd clerk-react
bun install
bun devInstall @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 install @clerk/clerk-reactyarn add @clerk/clerk-reactpnpm add @clerk/clerk-reactAdd your Clerk Publishable Key to your .env.local file. It can always be retrieved from the API keys page in the Clerk Dashboard.
- In the Clerk Dashboard, navigate to the API keys page.
- In the Quick Copy section, copy your Clerk Publishable Key.
- Paste your key into your
.env.localfile.
The final result should resemble the following:
VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEYImport 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.
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>,
)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.
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 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 or displays the sign-in modal.
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:
npm run devyarn devpnpm devbun devVisit your app's homepage at http://localhost:5173. Sign up to create your first user.
Next step: Add routing with React Router
React Router can be integrated with Clerk in two ways:
- As a framework: Use Clerk's built-in React Router integration
- As a library: Manually integrate React Router into your Clerk application using library mode
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
Last updated on