Docs

You are viewing an archived version of the docs.Go to latest version

<ClerkProvider>

The <ClerkProvider> component wraps your React application to provide active session and user context to Clerk's hooks and other components.

Usage

The <ClerkProvider> component must be added to your React entrypoint.

The <ClerkProvider> component needs to access headers to authenticate correctly. This means anything wrapped by the provider will be opted into dynamic rendering at request time. If you have static-optimized or ISR pages that you would prefer not to be opted into dynamic rendering, make sure they are not wrapped by <ClerkProvider>.

This is easiest to accomplish by ensuring that <ClerkProvider> is added further down the tree to wrap route groups that explicitly need authentication instead of having the provider wrap your application root as recommended above. For example, if your project includes a set of landing/marketing pages as well as a dashboard that requires sign-in, you would create separate (marketing) and (dashboard) route groups. Adding <ClerkProvider> to the (dashboard)/layout.jsx layout file will ensure that only those routes are opted into dynamic rendering, allowing the marketing routes to be statically optimized.

Note

The root layout is a server component. If you plan to use the <ClerkProvider> outside the root layout, it will need to be a server component as well.

app/layout.tsx
import React from "react";
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <title>Next.js 13 with Clerk</title>
      </head>
      <ClerkProvider>
        <body>{children}</body>
      </ClerkProvider>
    </html>
  );
}
_app.tsx
import { ClerkProvider } from "@clerk/nextjs";
import type { AppProps } from "next/app";

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClerkProvider {...pageProps}>
    <Component {...pageProps} />
    </ClerkProvider>
  );
}

export default MyApp;
index.tsx
import React from "react";
import ReactDOM from "react-dom";
import { ClerkProvider } from "@clerk/clerk-react";
import App from "./App";

const publishableKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;

ReactDOM.render(
  <React.StrictMode>
    <ClerkProvider publishableKey={publishableKey}>
      <App/>
    </ClerkProvider>
  </React.StrictMode>,
  document.getElementById("root")
);

Other meta-frameworks, like Remix and Gatsby, have wrappers around <ClerkProvider> to make their integrations tighter.

Properties

  • Name
    publishableKey
    Type
    string
    Description

    Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the API Keys page.

  • Name
    frontendApi
    Type
    string
    Description

    The frontend API host for your instance. This can be found in your Clerk Dashboard on the API Keys page under the Advanced section.

  • Name
    navigate?
    Type
    (to: string) => Promise<unknown> | void
    Description

    A function which takes the destination path as an argument and performs a "push" navigation.

  • Name
    clerkJSUrl?
    Type
    string
    Description

    Define the URL that @clerk/clerk-react should hot-load @clerk/clerk-js from.

  • Name
    clerkJSVariant?
    Type
    string
    Description

    If your web application only uses Control components, you can set this value to headless and load a minimal ClerkJS bundle for optimal page performance.

  • Name
    clerkJSVersion?
    Type
    string
    Description

    Define the npm version for @clerk/clerk-js.

  • Name
    supportEmail?
    Type
    string
    Description

    Optional support email for display in authentication screens. Will only affect Clerk Components and not Account Portal pages.

  • Name
    appearance?
    Type
    Appearance | undefined
    Description

    Optional object to style your components. Will only affect Clerk Components and not Account Portal pages.

  • Name
    localization
    Type
    Localization | undefined
    Description

    Optional object to localize your components. Will only affect Clerk Components and not Account Portal pages.

  • Name
    allowedRedirectOrigins?
    Type
    Array<string | RegExp>
    Description

    Optional array of domains used to validate against the query param of an auth redirect. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console.

  • Name
    afterSignInUrl?
    Type
    string
    Description

    The default URL to use after the user signs in.

  • Name
    afterSignUpUrl?
    Type
    string
    Description

    The default URL to use after the user signs up.

  • Name
    isSatellite?
    Type
    boolean | ((url: URL) => boolean)
    Description

    This option defines that the application is a satellite application.

  • Name
    domain?
    Type
    string | ((url: URL) => boolean)
    Description

    This option sets the domain of the satellite application. If your application is a satellite application, this option is required.

  • Name
    signInUrl
    Type
    string
    Description

    This url will be used for any redirects that might happen and needs to point to your primary application. This option is optional for production instances and required for development instances.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on