Search…
Get started with React
Learn to install and initialize Clerk in a new Create React App.

Overview

Clerk is the easiest way to add authentication and user management to your React application. This guide will you walk you through the necessary steps to install and use Clerk in a new create-react-app application. For more in-depth guides, check out our Popular Guides section.
After following this guide, you should have a working React app complete with:
    Fully fledged sign in and sign up flows.
    Google social login.
    Secure email/password authentication.
    A prebuilt user profile page.

Before you start

Creating a new React app

Start by creating a new React application - this is usually done using the create-react-app CLI:
npm
yarn
1
npx create-react-app
Copied!
1
yarn create react-app
Copied!
If you wish to use Typescript, just add --typescript to the commands above. Clerk is written in Typescript, so it works out of the box without any extra configuration. For more information, you can reference the create-react-app documentation.

Installing Clerk

One you have a React app ready, you need to install the Clerk React SDK. This will give you access to our prebuilt Clerk Components and React hooks.
npm
yarn
1
# Navigate to your application's root directory
2
# This should be the actual name from
3
# the previous step
4
cd my-app
5
​
6
# Install the clerk-react package
7
npm install @clerk/clerk-react
Copied!
1
# Navigate to your application's root directory
2
cd yourapp
3
​
4
# Install the clerk-react package
5
yarn add @clerk/clerk-react
Copied!
Now, we need to set the CLERK_FRONTEND_API environment variable. Go to the Clerk Dashboard, select your Application, and navigate to Development ➜ Instance configuration and copy the Frontend API field.
Getting your Frontend API key
Then, create a file named .env.local in your application root. Any variables inside this file with the REACT_APP_ prefix will be accessible in your React code via process.env.REACT_APP_VAR_NAME. Create a REACT_APP_CLERK_FRONTEND_API variable and set it to the Frontend API you copied earlier:
1
# Create the .env.local file
2
touch .env.local
3
4
# Add the environment variable. Don't forget to
5
# replace [your-frontend-api] with the actual Frontend API key
6
echo "REACT_APP_CLERK_FRONTEND_API=[your-frontend-api]" > .env.local
Copied!
Clerk is now successfully installed πŸŽ‰ To run your app, start the development server and navigate to http://localhost:3000.
npm
yarn
1
npm start
Copied!
1
yarn start
Copied!
For more details, consult the Clerk React installation page.

Adding <ClerkProvider />

Clerk requires your application to be wrapped in the <ClerkProvider/> context. In React, we add this in src/App.jsx.
Wrap your app with <ClerkProvider/> and pass the REACT_APP_CLERK_FRONTEND_API env variable you just created to the frontendApi prop. Replace your src/App.jsx with:
src/App.jsx
1
import React from "react";
2
import "./App.css";
3
// Import ClerkProvider
4
import { ClerkProvider } from "@clerk/clerk-react";
5
​
6
// Get the Frontend API from the environment
7
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
8
​
9
function App() {
10
return (
11
// Wrap your entire app with ClerkProvider
12
// Don't forget to pass the frontendApi prop
13
<ClerkProvider frontendApi={frontendApi}>
14
<Hello />
15
</ClerkProvider>
16
);
17
}
18
​
19
function Hello() {
20
return <div>Hello from Clerk</div>;
21
}
22
​
23
export default App;
Copied!
Navigate to http://localhost:3000 to view the changes. Now, let's add a router.

Adding a router

<ClerkProvider/> also accepts a navigate prop that enables Clerk to navigate inside your application without a full page reload, using the same routing logic your app does. Our display components use this prop when navigating between subpages, and when navigating to callback URLs.
You can pass the navigate prop a function which takes the destination URL as an argument and performs a "push" navigation. You should not implement the push yourself, but instead wrap the push function provided by your router.
Most React apps use the popular react-router-dom router, which is also what we'll be using for this guide. Install it by running the following command:
npm
yarn
1
npm i react-router-dom
Copied!
1
yarn add react-router-dom
Copied!
Wrap your <App/> component with the router by modifying the src/index.jsxfile as shown below:
src/index.jsx
1
import React from "react";
2
import ReactDOM from "react-dom";
3
import "./index.css";
4
import App from "./App";
5
import reportWebVitals from "./reportWebVitals";
6
​
7
// Import the BrowserRouter from the react-router-dom package
8
import { BrowserRouter } from "react-router-dom";
9
​
10
ReactDOM.render(
11
<React.StrictMode>
12
{/* Wrap your App component with the Router */}
13
<BrowserRouter>
14
<App />
15
</BrowserRouter>
16
</React.StrictMode>,
17
document.getElementById("root")
18
);
19
​
20
reportWebVitals();
Copied!
The last step is to give ClerkProvider access to your router, by adding the navigate prop. In src/App.jsx import and use the useHistory hook, as shown in the example:
src/App.jsx
1
import React from "react";
2
import "./App.css";
3
import { ClerkProvider } from "@clerk/clerk-react";
4
// import the useHistory hook
5
import { useHistory } from "react-router-dom";
6
​
7
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
8
​
9
function App() {
10
const { push } = useHistory();
11
​
12
return (
13
// Pass the push method to the navigate prop
14
<ClerkProvider frontendApi={frontendApi} navigate={(to) => push(to)}>
15
<Hello />
16
</ClerkProvider>
17
);
18
}
19
​
20
function Hello() {
21
return <div>Hello from Clerk</div>;
22
}
23
​
24
export default App;
Copied!
The navigate function must return the result of the push function.
Your app is now configured πŸŽ‰ Next, let's see how you can use Clerk to require authentication before navigating to a protected page.

Requiring authentication

The easiest way to require authentication before showing a protected page, is to use our Control Components:
    ​<SignedIn/>: Renders its children only when a user is signed in.
    ​<SignedOut/>: Renders its children only when there's no active user.
    ​<RedirectToSignIn/>: Triggers a redirect to the sign in page.
The following example shows you how to compose our flexible Control Components to build auth flows that match your needs. Please note that you don't need to use any additional APIs, everything shown below is just Javascript.
src/App.jsx
1
import React from "react";
2
import "./App.css";
3
import {
4
ClerkProvider,
5
SignedIn,
6
SignedOut,
7
UserButton,
8
useUser,
9
RedirectToSignIn,
10
} from "@clerk/clerk-react";
11
import { useHistory } from "react-router-dom";
12
​
13
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
14
​
15
function App() {
16
const { push } = useHistory();
17
​
18
// If the current route is listed as public, render it directly
19
// Otherwise, use Clerk to require authentication
20
return (
21
<ClerkProvider frontendApi={frontendApi} navigate={(to) => push(to)}>
22
<SignedIn>
23
<Hello />
24
</SignedIn>
25
<SignedOut>
26
<RedirectToSignIn />
27
</SignedOut>
28
</ClerkProvider>
29
);
30
}
31
​
32
function Hello() {
33
return <div>Hello from Clerk</div>;
34
);
35
}
36
​
Copied!
Visit https://localhost:3000 to see your page - you'll immediately get redirected to the Clerk Hosted Sign In page:
The default Clerk <SignIn/> component

Hello, world!

That's all you need to start using Clerk. Now you can say hello to your user!
Let's edit the <Hello/> component. We're going to use the useUser hook and the UserButton component as shown in the example:
src/App.jsx
1
import React from "react";
2
import "./App.css";
3
import {
4
ClerkProvider,
5
SignedIn,
6
SignedOut,
7
UserButton,
8
useUser,
9
RedirectToSignIn,
10
} from "@clerk/clerk-react";
11
import { useHistory } from "react-router-dom";
12
​
13
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
14
​
15
function App() {
16
const { push } = useHistory();
17
​
18
return (
19
<ClerkProvider frontendApi={frontendApi} navigate={(to) => push(to)}>
20
<SignedIn>
21
<Hello />
22
</SignedIn>
23
<SignedOut>
24
<RedirectToSignIn />
25
</SignedOut>
26
</ClerkProvider>
27
);
28
}
29
​
30
function Hello() {
31
// Get the user's first name
32
const { firstName } = useUser();
33
​
34
return (
35
<div className="App-header">
36
{/* Mount the UserButton component */}
37
<UserButton />
38
<div>Hello, {firstName}!</div>
39
</div>
40
);
41
}
42
​
43
export default App;
44
​
Copied!
Visit https://localhost:3000 again to see your page. If you haven't signed in yet, you will be redirected to the sign in page. Sign in using your preferred method and the home page will become accessible:
The home page showing an expanded <UserButton/> and the user's first name
And that's all!
By default, you app will use the Clerk Hosted Pages to display the sign in and sign up flows. Check the documentation of the <SignIn/> and <SignUp/> components to learn how you can mount them directly in your app.

Next steps

You now have a working React + Clerk app. Going forwards, you can:
Last modified 2mo ago