Next.js Quickstart (Pages Router)

Install @clerk/nextjs

The Clerk Next.js SDK gives you access to prebuilt components, React hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

Set your Clerk API keys

Add clerkMiddleware() to your app

clerkMiddleware() grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

1. Create a middleware.ts file.

   • If you're using the /src directory, create middleware.ts in the /src directory.
   • If you're not using the /src directory, create middleware.ts in the root directory alongside .env.

2. In your middleware.ts file, export the clerkMiddleware() helper:

   import { clerkMiddleware } from '@clerk/nextjs/server'
   
   export default clerkMiddleware()
   
   export const config = {
     matcher: [
       // Skip Next.js internals and all static files, unless found in search params
       '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
       // Always run for API routes
       '/(api|trpc)(.*)',
     ],
   }

3. By default, clerkMiddleware() will not protect any routes. All routes are public and you must opt-in to protection for routes. See the clerkMiddleware() reference to learn how to require authentication for specific routes.

Add <ClerkProvider> and Clerk components to your app

The <ClerkProvider> component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with <ClerkProvider> to make authentication globally accessible. See the reference docs for other configuration options.

You can control which content signed-in and signed-out users can see with Clerk's prebuilt control components. Create a header using the following components:

• <SignedIn>: Children of this component can only be seen while signed in.

• <SignedOut>: Children of this component can only be seen while signed out.

• <UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.

• <SignInButton />: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.

  import '@/styles/globals.css'
  import { ClerkProvider, SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
  import type { AppProps } from 'next/app'
  
  function MyApp({ Component, pageProps }: AppProps) {
    return (
      <ClerkProvider
        {...pageProps}
        appearance={{
          cssLayerName: 'clerk',
        }}
      >
        <SignedOut>
          <SignInButton />
        </SignedOut>
        <SignedIn>
          <UserButton />
        </SignedIn>
        <Component {...pageProps} />
      </ClerkProvider>
    )
  }
  
  export default MyApp

Update globals.css

In the previous step, the cssLayerName property is set on the <ClerkProvider> component. Now, you need to add the following line to the top of your globals.css file in order to include the layer you named in the cssLayerName property. The example names the layer clerk but you can name it anything you want. These steps are necessary for v4 of Tailwind as it ensures that Tailwind's utility styles are applied after Clerk's styles.

Create your first user

1. Run your project with the following command:

   npm

   yarn

   pnpm

   bun

   npm run dev

   yarn dev

   pnpm dev

   bun dev

2. Visit your app's homepage at http://localhost:3000⁠.

3. Click "Sign up" in the header and authenticate to create your first user.