Generic

This guide will help you install and initialize Clerk, so you can take advantage of our context utilities, control components, and display components in your React application.

1. Install the NPM package

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 host prop with the Client API host found in your dashboard.

<ClerkProvider host="auth.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>
      // Wrap ClerkProvider so we can use the useHistory() hook
      <ClerkProviderWithNavigate>
        // Your application code here
      </ClerkProviderWithNavigate>
    </Router>
  );
}

function ClerkProviderWithNavigate({ children }) {
  const { push } = useHistory();
  return (
    <ClerkProvider
      host="auth.abc123.lcl.dev"
      navigate={(to) => {
        return push(new URL(to).pathname);
      }}
    >
      {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 host="auth.abc123.lcl.dev" navigate={(to) => push(to)}>
      <Component {...pageProps} />
    </ClerkProvider>
  );
}

export default MyApp;

1. Install the NPM package#

2. Find your React entrypoint#

3. Import and initialize Clerk#

4. The navigate prop#

React Router#