Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

Next.js Quickstart

Protect your Next.js application with Clerk auth in less than ten minutes. This guide will show you how to install Clerk, add middleware to protect specific routes, and embed the <UserButton /> component for account management.

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

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

/src/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>
  )
}
_app.tsx
  import '@/styles/globals.css'
  import { ClerkProvider } from "@clerk/nextjs";
  import type { AppProps } from "next/app";
  function MyApp({ Component, pageProps }: AppProps) {
    return (
      <ClerkProvider {...pageProps}>
        <Component {...pageProps} />
      </ClerkProvider>
    );
  }
  export default MyApp;

Add authentication to your app

Now that Clerk is installed and mounted in your application, you can decide which pages are public and which should require authentication to access:

  1. Create a middleware.ts file at the root of your project, or in your src/ directory if you have one.
  2. In your middleware.ts file, export Clerk's authMiddleware()(opens in a new tab) helper. This helper enables authentication and blocks access for signed out visitors on routes that your middleware runs on.

Next.js middleware only runs on routes specified with matcher(opens in a new tab). Add the following code to your middleware.ts to protect your routes:

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
// See https://clerk.com/docs/references/nextjs/auth-middleware
// for more information about configuring your Middleware
export default authMiddleware({
  // Allow signed out users to access the specified routes:
  // publicRoutes: ['/anyone-can-visit-this-route'],
});
 
export const config = {
  matcher: [
    // Exclude files with a "." followed by an extension, which are typically static files.
    // Exclude files in the _next directory, which are Next.js internals.
    "/((?!.+\\.[\\w]+$|_next).*)",
    // Re-include any files in the api or trpc folders that might have an extension
    "/(api|trpc)(.*)"
  ]
};

Try accessing your app

Access your app to verify that authentication is enabled:

  1. Run your project with the following terminal command from the root directory of your project:
terminal
npm run dev
terminal
yarn dev
terminal
pnpm dev
  1. Visit http://localhost:3000 to access your app. The Middleware will redirect you to your Sign Up page, provided by Clerk's Account Portal feature.
  2. Sign up to gain access to your application.

Embed the <UserButton />

<UserButton /> is a prebuilt component that allows users to sign in, log out, and manage their account information.

Use the following code to add a <UserButton /> to your app:

app/page.tsx
import { UserButton } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <div className="h-screen">
      <UserButton />
    </div>
  )
}
pages/index.tsx
import { UserButton } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <>
      <header>
        <UserButton />
      </header>
      <div>Your home page's content can go here.</div>
    </>
  );
}

Then, visit your app's homepage at localhost:3000 to see the <UserButton /> in action. It should show your avatar from the account you signed in with.

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

What did you think of this content?

Clerk © 2024