Next.js Quickstart
You will learn the following:
- Install
@clerk/nextjs
- Set your Clerk API keys
- Add
clerkMiddleware()
- Add
<ClerkProvider />
and Clerk components
Before you start
Example repositories
Install @clerk/nextjs
Clerk's Next.js SDK gives you access to prebuilt components, React hooks, and helpers to make user authentication easier.
Run the following command to install the SDK:
Add the following keys to your .env.local
file. These keys can always be retrieved from the API keys page in the Clerk Dashboard.
- In the Clerk Dashboard, navigate to the API keys page.
- In the Quick Copy section, copy your Clerk Publishable and Secret Keys.
- Paste your keys into your
.env.local
file.
The final result should resemble the following:
Add clerkMiddleware()
to your app
clerkMiddleware()
grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware()
to your app, follow these steps:
-
Create a
middleware.ts
file.- If you're using the
/src
directory, createmiddleware.ts
in the/src
directory. - If you're not using the
/src
directory, createmiddleware.ts
in the root directory alongside.env.local
.
- If you're using the
-
In your
middleware.ts
file, export theclerkMiddleware()
helper: -
By default,
clerkMiddleware()
will not protect any routes. All routes are public and you must opt-in to protection for routes. See theclerkMiddleware()
reference to learn how to require authentication for specific routes.
Add <ClerkProvider>
and Clerk components to your app
The <ClerkProvider>
component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with <ClerkProvider>
to make authentication globally accessible. See the reference docs for other configuration options.
You can control which content signed-in and signed-out users can see with Clerk's prebuilt control components. Create a header using the following components:
<SignedIn>
: Children of this component can only be seen while signed in.<SignedOut>
: Children of this component can only be seen while signed out.<UserButton />
: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.<SignInButton />
: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
Select your preferred router to learn how to make this data available across your entire app:
Create your first user
Run your project with the following command:
Visit your app's homepage at http://localhost:3000. Sign up to create your first user.
Protect routes using Clerk Middleware
Learn how to protect specific routes from unauthenticated users.
Create custom sign-up and sign-in pages
Learn how add custom sign-up and sign-in pages with Clerk components.
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 app.
Client-side helpers
Learn more about Next.js client-side helpers and how to use them.
Next.js SDK Reference
Learn more about additional Next.js methods.
Deploy to Production
Learn how to deploy your Clerk app to production.
Deploy to Vercel
Learn how to deploy your Clerk app to production on Vercel.
Clerk + Next.js App Router Quickstart Repo
The official companion repo for Clerk's Next.js Quickstart using App Router.
Clerk + Next.js Pages Router Quickstart Repo
The official companion repo for Clerk's Next.js Quickstart using Pages Router.
Feedback
Last updated on