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> 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's layout, as shown in the following example:

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.

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