Global authentication context
A React application's root entry point needs Clerk authentication available to all routes and components.
Clerk · Component
ClerkProvider
ClerkProvider supplies Clerk session and user context to React hooks and components. Put it at the app entry point for global authentication, or lower in the tree for selected routes.
How it works
ClerkProvider is the React context boundary for Clerk authentication. Place it around the whole application for global access, or lower in the tree when only selected routes or components need Clerk; configure it with the instance publishable key and optional navigation settings.
Syntax
<ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/"><App /></ClerkProvider>Parameters
| Name | Type | Description |
|---|---|---|
publishableKey | string | The Clerk Publishable Key for your instance; when omitted, supported environment variables are read. |
afterSignOutUrl | string | The full URL or path to navigate to after signing out the current user is complete. |
Returns
A React provider component that supplies Clerk session and user context to descendants.
Key points
- Mounting it at the entry point makes Clerk authentication globally accessible.
- A narrower placement is appropriate when authentication is not needed everywhere.
- The publishableKey property identifies the Clerk instance used by the application.
- afterSignOutUrl configures the destination after the current user finishes signing out.
Common mistakes
- Wrapping only the authenticated portion can avoid applying Clerk to unrelated application areas.
- The publishable key can come from supported environment variables, but an explicit prop makes configuration visible.
Example: Provide Clerk context to a React app
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { ClerkProvider } from '@clerk/react';
const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
if (!publishableKey) throw new Error('Add your Clerk Publishable Key');
ReactDOM.createRoot(document.getElementById('root')!).render(
<ClerkProvider publishableKey={publishableKey} afterSignOutUrl="/">
<App />
</ClerkProvider>,
);Wrap the application at its entry point so Clerk authentication context is available to the app.
When to use it
Scoped authentication context
Only a dashboard or protected route group uses Clerk features while public pages do not.
Post-sign-out navigation
The application needs a defined destination after the active user signs out.
Interview questions
QWhat does ClerkProvider do, and where is it usually mounted?
ClerkProvider supplies session and user context to Clerk hooks and components. It is normally placed at the application entry point so authentication is available throughout the React tree.
Follow-up: How would you limit Clerk to authenticated routes? Render ClerkProvider deeper in the component tree around only those routes or components.
QHow is the Clerk publishable key configured?
Pass the instance's publishable key through the publishableKey property. In React, the provider can also read VITE_CLERK_PUBLISHABLE_KEY or CLERK_PUBLISHABLE_KEY when that property is omitted.
Follow-up: What should an application do if the key is missing? Fail during startup with a clear configuration error rather than rendering an unusable authentication flow.
QHow can sign-out navigation be configured?
The provider accepts configuration properties such as afterSignOutUrl, which controls where the user is sent after signing out. The documented React example wraps the app and sets this value to the root path.
Follow-up: Why might provider placement matter beyond authentication access? Moving it deeper lets unrelated parts of the application remain outside Clerk's context and configuration boundary.
Related
useAuthuseUserSignedInSignedOutUserButton