Installation

If you use a supported React framework, we recommend you reference its quick start instead of this generic installation guide:

1. Install clerk-react

Install Clerk's NPM package for React applications.

npm install @clerk/clerk-react
# or
yarn add @clerk/clerk-react

2. Find your React entrypoint

Find the file with the top-most React component.

  • create-react-app — Use src/index

  • Next.js — Use pages/_app. If you do not have a pages/_app file yet, add one using the Next.js documentation for a Custom `App`.

For other frameworks or custom buildpacks, generally the top-most React component will be in a file named index or app. You can also search for the file where ReactDOM.render gets called.

3. Import and initialize Clerk

In your entrypoint file, import ClerkProvider modules from our NPM package:

import { ClerkProvider } from "@clerk/clerk-react";

Finally, wrap your entire application with the ClerkProvider component. This is a react context provider that is required for our context utilities, control components, and display components.

Replace the frontendApi prop with the Frontend API host found in your dashboard.

<ClerkProvider frontendApi="clerk.abc123.lcl.dev">
{/* Your application tree here. */}
</ClerkProvider>

4. The navigate prop

The navigate prop enables Clerk to navigate inside your application without a full page reload. Our display components use this prop when navigating between subpages, and when navigating to callback URLs like afterSignIn.

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.

Below are examples for React Router and Next.js.

React Router

import { BrowserRouter as Router, useHistory } from "react-router-dom";
import { ClerkProvider } from "@clerk/clerk-react";
export default function App() {
return (
<Router>
<ClerkProviderWithNavigate>
{/* Your application tree here. */}
</ClerkProviderWithNavigate>
</Router>
);
}
// Wrap ClerkProvider so we can use the useHistory() hook
function ClerkProviderWithNavigate({ children }) {
const { push } = useHistory();
return (
<ClerkProvider
frontendApi="auth.abc123.lcl.dev"
navigate={(to) => {
return push(to);
}}
>
{children}
</ClerkProvider>
);
}

Next.js

// Contents of pages/_app.js
import { ClerkProvider } from "@clerk/clerk-react";
import { useRouter } from "next/router";
function MyApp({ Component, pageProps }) {
const { push } = useRouter();
return (
<ClerkProvider
frontendApi="auth.abc123.lcl.dev"
navigate={(to) => push(to)}
>
<Component {...pageProps} />
</ClerkProvider>
);
}
export default MyApp;