Skip to main content
Docs

Next.js Quickstart

You will learn the following:

  • Install @clerk/nextjs
  • Set your Clerk API keys
  • Add clerkMiddleware()
  • Add <ClerkProvider> and Clerk components

Before you start

Example repositories

Install @clerk/nextjs

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

Run the following command to install the SDK:

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

Set your Clerk API keys

.env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Add clerkMiddleware() to your app

clerkMiddleware() grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

  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 alongside .env.local.

  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

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.

You can control which content signed-in and signed-out users can see with Clerk's prebuilt control components. Create a header using the following components:

Select your preferred router to learn how to make this data available across your entire app:

app/layout.tsx
import { ClerkProvider, SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import './globals.css'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <header>
            <SignedOut>
              <SignInButton />
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          <main>{children}</main>
        </body>
      </html>
    </ClerkProvider>
  )
}
pages/_app.tsx
import '@/styles/globals.css'
import { ClerkProvider, SignInButton, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'
import type { AppProps } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClerkProvider {...pageProps}>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <UserButton />
      </SignedIn>
      <Component {...pageProps} />
    </ClerkProvider>
  )
}

export default MyApp

Create your first user

Run your project with the following command:

terminal
npm run dev
terminal
yarn dev
terminal
pnpm dev

Visit your app's homepage at http://localhost:3000. Sign up to create your first user.

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