Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev
nextjs's logo

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/>
    • Limit access to authenticated users
    • Embed the <UserButton/>

Before you start:

Example repositories
Blue cube icon

App router

Purple pages icon

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.

/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>
  )
}

Require authentication to access 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.

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.

Copy and paste the following code into your middleware.ts. With this, your entire application is protected.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
// This example protects all routes including api/trpc routes
// Please edit this to allow other routes to be public as needed.
// See https://clerk.com/docs/references/nextjs/auth-middleware for more information about configuring your Middleware
export default authMiddleware({});
 
export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

Try accessing your app now by visiting http://localhost:3000. The Middleware will redirect you to your Sign Up page, provided by Clerk's Account Portal feature. If you want to make other routes public, check out the authMiddleware reference page. Go ahead and sign up to get access to your application. Your app is now fully protected by Clerk!

Embed the <UserButton />

Clerk offers a set of prebuilt components to add functionality to your app with minimal effort. The <UserButton /> allows users to manage their account information and log out, completing the full authentication circle.

Add the <UserButton /> anywhere inside <ClerkProvider /> in your app. First, add import { UserButton } from "@clerk/nextjs"; to the top of your file. Then, add <UserButton afterSignOutUrl="/"/>. The afterSignOutUrl prop lets you customize what page the user will be redirected to after sign out.

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

Sign out of your application

Visit your Next.js application at localhost:3000, click on your avatar, and select Sign out. You are now back where you started: a sign-in form.

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

Use Clerk with Next.js 12 and older

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

Learn More

What did you think of this content?

Clerk © 2023