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. It also allows you to protect specific routes from unauthenticated users. 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)(.*)',
     ],
   }

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> 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.

Add the <ClerkProvider> component to your app, as shown in the following example:

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 a header with Clerk components

You can control which content signed-in and signed-out users can see with the prebuilt control components. The following example creates 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.
• <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.

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.