Next.js Quickstart (App Router)

Create a new Next.js app

If you don't already have a Next.js app, 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:

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.

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> 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 layout.tsx file. This:

• Adds the <ClerkProvider> component to your app's layout, 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.

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.

3. To make configuration changes to your Clerk development instance, claim the Clerk keys that were generated for you by selecting Configure your application in the bottom right of your app. This will associate the application with your Clerk account.