Skip to main content
Docs

Next.js Quickstart (App Router)

Use this pre-built prompt to get started faster.

Create a new Next.js application

Run the following command to create a new Next.js application. It will create an app with the name my-clerk-app, but you can replace it with any name you want.

terminal
npm create next-app@latest my-clerk-app -- --yes
terminal
yarn create next-app my-clerk-app --yes
terminal
pnpm create next-app my-clerk-app --yes
terminal
bun create next-app my-clerk-app --yes

Install @clerk/nextjs

Run the following command to install the Next.js SDK:

terminal
npm install @clerk/nextjs
terminal
yarn add @clerk/nextjs
terminal
pnpm add @clerk/nextjs
terminal
bun add @clerk/nextjs

Add clerkMiddleware() to your app

clerkMiddleware() grants you access to user authentication state throughout your app.

  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.

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

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

  1. Add the <ClerkProvider> component to your app's layout. This component provides Clerk's authentication context to your app.
  2. Copy and paste the following file into your layout.tsx file. This creates a header with Clerk's prebuilt components to allow users to sign in and out.
app/layout.tsx
import type { Metadata } from 'next'
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  SignedIn,
  SignedOut,
  UserButton,
} from '@clerk/nextjs'
import { Geist, Geist_Mono } from 'next/font/google'
import './globals.css'

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
})

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
})

export const metadata: Metadata = {
  title: 'Clerk Next.js Quickstart',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
    <ClerkProvider
      appearance={{
        cssLayerName: 'clerk',
      }}
    >
      <html lang="en">
        <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <SignedOut>
              <SignInButton />
              <SignUpButton>
                <button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
                  Sign Up
                </button>
              </SignUpButton>
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  )
}

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.

globals.css
@layer theme, base, clerk, components, utilities;

Create your first user

  1. Run your project with the following command:

    terminal
    npm run dev
    terminal
    yarn dev
    terminal
    pnpm dev
    terminal
    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.

It's time to build!

You've added Clerk to your Next.js app 🎉. From here, you can continue developing your application.

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.

Next steps

Create a custom sign-in or sign-up page

This tutorial gets you started with Clerk's <SignInButton /> component, which uses the Account Portal. If you don't want to use the Account Portal, read this guide about creating a custom authentication page.

Add custom onboarding to your authentication flow

If you need to collect additional information about users that Clerk's Account Portal or prebuilt components don't collect, read this guide about adding a custom onboarding flow to your authentication flow.

Protect specific routes

This tutorial taught you that by default, clerkMiddleware() will not protect any routes. Read this reference doc to learn how to protect specific routes from unauthenticated users.

Read user and session data

Learn how to use Clerk's hooks and helpers to access the active session and user data in your Next.js app.

Next.js SDK Reference

Learn more about the Clerk Next.js SDK and how to use it.

Deploy to Production

Learn how to deploy your Clerk app to production.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on