Next.js Quickstart (Pages Router)

Create a new Next.js app

If you don't already have a Next.js app (Pages Router), run the following commands to create a new one⁠.

Install @clerk/nextjs

The Clerk Next.js SDK gives you access to prebuilt components, 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. To add clerkMiddleware() to your app, follow these steps:

1. Create a proxy.ts file.

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

2. In your proxy.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)(.*)',
       // Always run for Clerk-specific frontend API routes
       '/__clerk/(.*)',
     ],
   }

3. By default, clerkMiddleware() will not protect any routes. All routes are public and you must opt-in to protection. To require a signed-in user, protect resources close to where they're used, as shown in the Pages Router examples in the guide on reading user data.

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.

Copy and paste the following code into your app. This:

• Adds the <ClerkProvider> to your app, providing Clerk's authentication context to your app.
• Creates a header with Clerk's prebuilt components to allow users to sign in and out, and display different content for signed-in and signed-out users.

This example uses the following components:

• <Show when="signed-in">: Children of this component can only be seen while signed in.
• <Show when="signed-out">: 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.
• <SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.

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.

Run your project

Run your project with the following command:

Create your first user

1. Visit your app's homepage at http://localhost:3000⁠.
2. Select "Sign up" on the page and authenticate to create your first user.