Skip to Content
Clerk logo

Clerk Docs

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

Next.js Quickstart

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
    • Specify which routes are publicly accessible
    • Enable users to manage their session with <UserButton />

Before you start:

Example repositories
Blue cube icon

App router

Purple pages icon

Pages router

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 keys

  1. If you don't have a .env.local file in the root directory of your Next.js project, create one now.
  2. Find your publishable key and secret key. If you're signed into Clerk, the .env.local snippet below will contain your keys. Otherwise:
  • Navigate to your Clerk Dashboard(opens in a new tab).
  • Select your application, then select 🔑 API Keys in the sidebar menu.
  • You can copy your keys from the Quick Copy section.
  1. Add your keys to your .env.local file.

The final result should look as follows:

.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 below 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, export Clerk's authMiddleware(opens in a new tab) helper:
middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware({});
  1. With authMiddleware(), authentication will be enabled by default on all routes that your Next.js middleware runs on, blocking access to all signed out visitors. You can specify valid routes using Next.js's matcher(opens in a new tab). Add the following code to your middleware.ts to protect your entire application:
middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware({
  // Routes that can be accessed while signed out
  publicRoutes: ['/anyone-can-visit-this-route'],
  // Routes that can always be accessed, and have
  // no authentication information
  ignoredRoutes: ['/no-auth-in-this-route'],
});
 
export const config = {
  // Protects all routes, including api/trpc.
  // See https://clerk.com/docs/references/nextjs/auth-middleware
  // for more information about configuring your Middleware
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

See the authMiddleware() docs to learn more about publicRoutes and ignoredRoutes.

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.
  3. Log into your new account. You should be able to access it now.

Embed the <UserButton />

<UserButton /> is a prebuilt component that allows users to log 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.

Sign out

Finally, use the <UserButton /> by selecting your avatar, then selecting Sign out.

Next steps

To see an example application that demonstrates user authentication, and session and organization management, explore one of Clerk's Next.js demo repos:

More resources

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

What did you think of this content?

Clerk © 2024