Get started with Next.js

Learn to install and initialize Clerk in a new Next.js application.

Overview

Clerk is the easiest way to add authentication and user management to your Next.js application. This guide will walk you through the necessary steps to install and use Clerk in a new Next.js application. For more in-depth guides, check out our Popular Guides section.

After following this guide, you should have a working Next.js app complete with:

  • Fully fledged sign in and sign up flows.

  • Google social login.

  • Secure email/password authentication.

  • A prebuilt user profile page.

Before you start

Creating a new Next.js app

Start by creating a new Next.js application - this is usually done using the Next.js CLI:

npm
yarn
npm
npx create-next-app
yarn
yarn create next-app

If you wish to use Typescript, just add --typescript to the commands above. Clerk is written in Typescript, so it works out of the box without any extra configuration. For more information, you can reference the Next.js documentation.

Installing Clerk

Once you have a Next.js app ready, you need to install the Clerk React SDK. This will give you access to our prebuilt Clerk Components and React hooks.

npm
yarn
npm
# Navigate to your application's root directory
cd yourapp
# Install the clerk/nextjs package
npm install @clerk/nextjs
yarn
# Navigate to your application's root directory
cd yourapp
# Install the clerk-react package
yarn add @clerk/clerk-react

Now, we need to set the CLERK_FRONTEND_API environment variable. Go to the Clerk Dashboard, select your Application, and navigate to Development Instance configuration and copy the Frontend API field.

Getting your Frontend API key

Then, create a file named .env.local in your application root. Any variables inside this file with the NEXT_PUBLIC_ prefix will be accessible in your Next.js code via process.env.NEXT_PUBLIC_VAR_NAME. Create a NEXT_PUBLIC_CLERK_FRONTEND_API variable and set it to the Frontend API you copied earlier:

# Create the .env.local file
touch .env.local
# Add the environment variable. Don't forget to
# replace [your-frontend-api] with the actual Frontend API key
echo "NEXT_PUBLIC_CLERK_FRONTEND_API=[your-frontend-api]" > .env.local

Clerk is now successfully installed 🎉

To run your app, start the development server and navigate to https://localhost:3000.

npm
yarn
npm
npm run dev
yarn
yarn dev

For more details, consult the Clerk React installation page.

Adding <ClerkProvider />

Clerk requires your application to be wrapped in the <ClerkProvider/> component. In Next.js, we add this in pages/_app.js.

pages/_app.jsx
import '../styles/globals.css';
import { ClerkProvider } from '@clerk/nextjs';
function MyApp({ Component, pageProps }) {
return (
// Wrap your entire app with ClerkProvider
<ClerkProvider>
<Component {...pageProps} />
</ClerkProvider>
);
}
export default MyApp;

<ClerkProvider/> from the @clerk/nextjs package is already configured to using the same routing logic with Next.js. This makes sure that navigating between subpages and when navigating to callback URLs, routing remains consistent.

Your app is now configured 🎉

Next, let's see how you can use Clerk to require authentication before navigating to a protected page.

Requiring authentication

The easiest way to require authentication before showing a protected page, is to use our Control Components:

The following example shows you how to compose our flexible Control Components to build authentication flows that match your needs. Please note that you don't need to use any additional APIs, everything shown below is just Javascript.

pages/_app.tsx
import '../styles/globals.css';
import { ClerkProvider, SignedIn, SignedOut, RedirectToSignIn } from '@clerk/nextjs';
import { useRouter } from 'next/router';
// List pages you want to be publicly accessible, or leave empty if
// every page requires authentication. Use this naming strategy:
// "/" for pages/index.js
// "/foo" for pages/foo/index.js
// "/foo/bar" for pages/foo/bar.js
// "/foo/[...bar]" for pages/foo/[...bar].js
const publicPages = [];
function MyApp({ Component, pageProps }) {
// Get the pathname
const { pathname } = useRouter();
// Check if the current route matches a public page
const isPublicPage = publicPages.includes(pathname);
// If the current route is listed as public, render it directly
// Otherwise, use Clerk to require authentication
return (
<ClerkProvider>
{isPublicPage ? (
<Component {...pageProps} />
) : (
<>
<SignedIn>
<Component {...pageProps} />
</SignedIn>
<SignedOut>
<RedirectToSignIn />
</SignedOut>
</>
)}
</ClerkProvider>
);
}
export default MyApp;

Visit https://localhost:3000 to see your page. The home "/" page is not listed in the publicPages array, so you'll immediately get redirected to the Clerk Hosted Sign In page:

The default Clerk <SignIn/> component

Hello, world!

That's all you need to start using Clerk. Now you can say hello to your user!

Edit the pages/index.js page. We're going to use the useUser hook and the UserButton component as shown in the example:

pages/index.js
import styles from "../styles/Home.module.css";
import { useUser, UserButton } from "@clerk/nextjs";
export default function Home() {
// Get the current user's firstName
const { firstName } = useUser();
return (
<div className={styles.container}>
<header>
{/* Mount the UserButton component */}
<UserButton />
</header>
<main>Hello, {firstName}!</main>
</div>
);
}

Visit https://localhost:3000 again to see your page. If you haven't signed in yet, you will be redirected to the sign in page. Sign in using your preferred method and the home page will become accessible:

The home page showing an expanded <UserButton/> and the user's first name

And that's all!

By default, your app will use the Clerk Hosted Pages to display the sign in and sign up flows. Check the documentation of the <SignIn/> and <SignUp/> components to learn how you can mount them directly in your app.

Next steps

You now have a working Next.js + Clerk app. Going forwards, you can: