Skip to Content
You are viewing a beta version of Clerk Docs
Visit the latest docs
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

Next.js Quickstart

You will learn how to:

    • 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
Blue cube icon

App router

Purple pages icon

Pages router

You're reading the quickstart guide for the beta of the next major version of the Next.js SDK. For more information about the changes from the current version, check out the upgrade guide!

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@beta
terminal
yarn add @clerk/nextjs@beta
terminal
pnpm add @clerk/nextjs@beta

Set your environment variables

.env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
CLERK_SECRET_KEY={{secret}}

Add <ClerkProvider> to your app

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

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

app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs'
import './globals.css'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  )
}

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. Your middleware.ts file should be placed inside the root directory alongside .env.local, or inside the src/ directory if you are using it.
  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: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
};
  1. 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.

Create a header with Clerk components

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 or displays the sign-in modal.
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}>
      <header>
        <SignedOut>
          <SignInButton />
        </SignedOut>
        <SignedIn>
          <UserButton />
        </SignedIn>
      </header>
      <Component {...pageProps} />
    </ClerkProvider>
  )
}
 
export default MyApp;

Create a home page

To render the header you just created, create a simple homepage.

app/page.tsx
 
export default function Home() {
  return (
    <h1>Home Page</h1>
  )
}
pages/index.tsx
 
export default function Home() {
  return (
    <h1>Home Page</h1>
  )
}

Then, visit your app's homepage at localhost:3000 while signed out to see the sign-in button. Once signed in, your app will render the user button.

Next steps

Create custom sign-up and sign-in pages

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

Learn More

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.

Learn More

Client Side Helpers

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

Learn More

Next.js SDK Reference

Learn more about additional Next.js methods.

Learn More

Deploy to Production

Learn how to deploy your Clerk app to production.

Learn More

Deploy to Vercel

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

Learn More

Clerk + Next.js App Router Quickstart Repo

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

Learn More

Clerk + Next.js Pages Router Quickstart Repo

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

Learn More

Last updated on March 25, 2024

What did you think of this content?

Clerk © 2024