Add authentication and user management to your Next.js app with Clerk in 7 minutes

You will learn how to:

Install @clerk/nextjs
Set up your environment keys
Wrap your Next.js app in <ClerkProvider />
Add Middleware to your app
Use Clerk components to protect your content
Embed the <UserButton /> and <SignInButton />
Deploy your application

Before you start:

Example repositories

App router

Pages router

Install `@clerk/nextjs`

Clerk's Next.js SDK gives you access to prebuilt components, hooks, and helpers for Next.js Server Components, Route Handlers and Middleware. Install it by running the following command in your terminal:

terminal
npm install @clerk/nextjs

terminal
yarn add @clerk/nextjs

terminal
pnpm add @clerk/nextjs

Set environment keys

In your Next.js project's root folder, you may have an .env.local file alongside package.json and other configuration files. If you don't see it, create it.

Add the following code to your .env.local file to set your public and secret keys.

Pro tip! If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon.

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

This sets your public and secret keys.

Wrap your app in `<ClerkProvider>`

The <ClerkProvider> component provides active session and user context to Clerk's hooks and other components. Import it into your app by adding import { ClerkProvider } from '@clerk/nextjs' at the top of your file.

The app/layout.tsx file might be in your src folder if it isn't in your root folder.

For this project, it makes sense to wrap the <html /> element with <ClerkProvider>. This makes the active session and user context accessible anywhere within the 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>
  )
}

For this project, it makes sense to wrap the <Component /> element with <ClerkProvider>. This makes the active session and user context accessible anywhere within MyApp.

_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 Middleware to your app

Middleware grants you access to user authentication state throughout your application, on any route or page. While clerkMiddleware() offers the capability to protect routes, it does not enforce protection by default. Please see clerkMiddleware() and the Route Protection for information on protecting routes.

To get started, create a middleware.ts file. If your application uses the src/ directory, your middleware.ts file should be placed inside the src/ folder. If you are not using a src/ directory, place the middleware.ts file in your root directory alongside .env.local.

Then, copy and paste the following code into your middleware.ts.

middleware.ts
import { clerkMiddleware } from "@clerk/nextjs/server";
 
export default clerkMiddleware()
 
export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

Use Clerk components to protect your content

Clerk provides prebuilt components that control content access based on user authentication and permissions. These components can be used to restrict access to specific content or entire pages.

To manage content visibility for signed-in users, use the <SignedIn> component:

Enclose content within the <SignedIn> tags to make it viewable only by users who are currently signed in.
Content outside of these tags remains accessible to both signed-in and signed-out users.

To manage content visibility for signed-out users, use the <SignedOut> component:

Enclose content within the <SignedOut> tags to make it visible only to users who are currently not signed in.
Content outside of these tags is only accessible to both signed-in and signed-out users.

app/page.tsx
import { SignedIn, SignedOut } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <div className="h-screen">
      <SignedOut>
        <p>This content is public. Only signed out users can see this.</p>
      </SignedOut>
      <SignedIn>
        <p>This content is private. Only signed in users can see this.</p>
      </SignedIn>
    </div>
  )
}

pages/index.tsx
import { SignedIn, SignedOut } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <div>
      <SignedOut>
        <p>This content is public. Only signed out users can see this.</p>
      </SignedOut>
      <SignedIn>
        <p>This content is private. Only signed in users can see this.</p>
      </SignedIn>
    </div>
  );
}

Try accessing your app now by visiting http://localhost:3000 to see what signed out users will see. Next you will add a button so you can sign in and see the content within the <SignedIn /> component.

The <UserButton /> allows users to manage their account information and log out, completing the full authentication circle. The [<SignInButton />(/docs/components/unstyled/sign-in-button)] is an unstyled component designed to wrap around your button. It can also act as a basic button on its own.

To add the <UserButton /> and <SignInButton />, do the following:

Add import { UserButton, SignInButton } from "@clerk/nextjs"; to the top of your file.
Ddd <SignInButton /> comoponent inside of the <SignedOut /> components
Add <UserButton/> inside of the <SignedIn /> components.

app/page.tsx
import { SignInButton, SignedIn, SignedOut, UserButton } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <div className="h-screen">
      <SignedOut>
        <SignInButton />
        <p>This content is public. Only signed out users can see this.</p>
      </SignedOut>
      <SignedIn>
        <UserButton />
        <p>This content is private. Only signed in users can see this.</p>
      </SignedIn>
    </div>
  )
}

pages/index.tsx
import { SignInButton, SignedIn, SignedOut, UserButton } from "@clerk/nextjs";
 
export default function Home() {
  return (
    <div>
      <SignedOut>
        <SignInButton />
        <p>This content is public. Only signed out users can see this.</p>
      </SignedOut>
      <SignedIn>
        <UserButton />
        <p>This content is private. Only signed in users can see this.</p>
      </SignedIn>
    </div>
  );
}

Visit http://localhost:3000] and try using the <SignInButton /> to sign in and see the protected content. Once signed in, you can use the <UserButton /> to sign out and see the unprotected content again.

Deploy your application

You're ready to deploy your app to production and welcome new users!

You're authenticated!

Congratulations! Your app is now only available to authenticated users. But this is just the first step.

If you would like a repository that demonstrates many of the features Clerk has to offer, such as user, session, and organization management, check out one of Clerk's demo repositories:

Next step: Route Protection

Learn about the options available for protecting your routes, from using clerkMiddleware() to layouts or even per page. Read the Route Protection guide to learn more.

You can also learn more about Clerk components, how to customize them, and how to use Clerk's client side helpers. The following guides are good places to start.

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

Use Clerk with Next.js 12 and older

Learn how to use Clerk with older versions of Next.js.

Learn More

Add authentication and user management to your Next.js app with Clerk in 7 minutes

You will learn how to:

Before you start:

Set environment keys

Wrap your app in <ClerkProvider>

Add Middleware to your app

Use Clerk components to protect your content

Embed the <UserButton /> and <SignInButton />

Deploy your application

You're authenticated!

Next step: Route Protection

Create custom sign-up and sign-in pages

Read user and session data

Client Side Helpers

Next.js SDK Reference

Use Clerk with Next.js 12 and older

Wrap your app in `<ClerkProvider>`

Embed the `<UserButton />` and `<SignInButton />`