Skip to main content

Next.js Quickstart (App Router)

Use this prebuilt prompt to get started faster.

Example repository

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.

npm create next-app@latest clerk-nextjs -- --yes
cd clerk-nextjs
npm install
pnpm create next-app clerk-nextjs --yes
cd clerk-nextjs
pnpm install
yarn create next-app clerk-nextjs --yes
cd clerk-nextjs
yarn install
bunx create-next-app clerk-nextjs --yes
cd clerk-nextjs
bun install

Install @clerk/nextjs

The Clerk Next.js SDKNext.js Icon gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

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

Add clerkMiddleware() to your app

clerkMiddleware()Next.js Icon 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:

Important

If you're using Next.js ≤15, name your file middleware.ts instead of proxy.ts. The code itself remains the same; only the filename changes.

  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:

    proxy.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)(.*)',
    // 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 for routes. See the clerkMiddleware() referenceNext.js Icon 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.
app/layout.tsx
import type { Metadata } from 'next'
import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from '@clerk/nextjs'
import { Geist, Geist_Mono } from 'next/font/google'
import './globals.css'


14 lines collapsedconst 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 (
    <html lang="en">
      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
        <ClerkProvider>
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <Show when="signed-out">
              <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>
            </Show>
            <Show when="signed-in">
              <UserButton />
            </Show>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}

This example uses the following components:

Run your project

Run your project with the following command:

npm run dev
pnpm run dev
yarn dev
bun run dev

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.

Next steps

Explore the most relevant next steps for your SDK using the following guides.

Prebuilt components

Learn how to add Clerk's prebuilt authentication and user-management UI to your app.

Build custom flows

Learn how to build custom user interfaces entirely from scratch using the Clerk API.

Protect content and read user data

Learn how to use Clerk's helpers to protect content and read user data in your app.

Customization & localization

Learn how to customize and localize Clerk components.

More to explore

Explore additional Clerk features that help you build, manage, and grow your application.

  • Organizations - Organizations are shared accounts that let teams collaborate, manage members and roles, and control access to shared resources.
  • Billing - Billing enables you to manage subscriptions, free trials, payments, plans, and billing-related webhook events for B2C and B2B applications.
  • Waitlist - Waitlist lets you collect signups and control access to new products or features before launch through a simple, integrated workflow.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub