Docs

Next.js Quickstart

You will learn the following:

  • Install @clerk/nextjs
  • Set up your environment keys to test your app locally
  • Add <ClerkProvider /> to your application
  • Use Clerk middleware to implement route-specific authentication
  • Create a header with Clerk components for users to sign in and out

Before you start

Example repositories

Install @clerk/nextjs

Clerk's Next.js SDK has prebuilt components, React hooks, and helpers to make user authentication easier.

To get started using Clerk with Next.js, add the SDK to your project:

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

Set your environment variables

  1. Navigate to the Clerk Dashboard.
  2. In the top navigation, select Configure. Then in the sidebar, select API Keys.
  3. In the Quick Copy section, copy your Clerk publishable and secret key.
  4. Paste your keys into your .env.local file.

The final result should resemble the following:

.env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Add Middleware to your application

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

  1. Create a middleware.ts file.

    • If you're using the /src directory, place middleware.ts in the /src directory.
    • If you're not using the /src directory, place middleware.ts in the root directory alongside .env.local.

  2. In your middleware.ts, export Clerk's 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 components to your app

All Clerk hooks and components must be children of the <ClerkProvider> component, which provides active session and user context.

You can control which content signed in and signed out users can see with Clerk's prebuilt components. To get started, create a header for your users to sign in or out. To do this, you will use:

  • <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 />: A prebuilt component that comes styled out of the box to show the avatar from the account the user is signed in with.
  • <SignInButton />: An unstyled component that links to the sign-in page. For this example, because you have not specified any props or environment variables for the sign-in URL, the component will link to the Account Portal sign-in page.

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

Protect routes using Clerk Middleware

Learn how to protect specific routes from unauthenticated users.

Create custom sign-up and sign-in pages

Learn how add custom sign-up and sign-in pages with Clerk components.

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 application.

Client Side Helpers

Learn more about Next.js client-side helpers and how to use them.

Next.js SDK Reference

Learn more about additional Next.js methods.

Deploy to Production

Learn how to deploy your Clerk app to production.

Deploy to Vercel

Learn how to deploy your Clerk app to production on Vercel.

Clerk + Next.js App Router Quickstart Repo

The official companion repo for Clerk's Next.js Quickstart using App Router.

Clerk + Next.js Pages Router Quickstart Repo

The official companion repo for Clerk's Next.js Quickstart using Pages Router.

Feedback

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

Last updated on