Next.js Quickstart
Protect your Next.js application with Clerk auth in less than ten minutes. This guide will show you how to install Clerk, add middleware to protect specific routes, and embed the <UserButton /> component for account management.
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:
npm install @clerk/nextjsyarn add @clerk/nextjspnpm add @clerk/nextjsNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEYAdd <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 to learn how to make this data available across your entire app:
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>
)
} 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:
- Create a
middleware.tsfile at the root of your project, or in yoursrc/directory if you have one. - In your
middleware.tsfile, export Clerk'sauthMiddleware()helper. This helper enables authentication and blocks access for signed out visitors on routes that your middleware runs on.
Next.js middleware only runs on routes specified with matcher. Add the following code to your middleware.ts to protect your routes:
import { authMiddleware } from "@clerk/nextjs";
// See https://clerk.com/docs/references/nextjs/auth-middleware
// for more information about configuring your Middleware
export default authMiddleware({
// Allow signed out users to access the specified routes:
// publicRoutes: ['/anyone-can-visit-this-route'],
});
export const config = {
matcher: [
// Exclude files with a "." followed by an extension, which are typically static files.
// Exclude files in the _next directory, which are Next.js internals.
"/((?!.+\\.[\\w]+$|_next).*)",
// Re-include any files in the api or trpc folders that might have an extension
"/(api|trpc)(.*)"
]
};Try accessing your app
Access your app to verify that authentication is enabled:
- Run your project with the following terminal command from the root directory of your project:
npm run devyarn devpnpm dev- Visit
http://localhost:3000to access your app. The Middleware will redirect you to your Sign Up page, provided by Clerk's Account Portal feature. - Sign up to gain access to your application.
Embed the <UserButton />
<UserButton /> is a prebuilt component that allows users to sign in, log out, and manage their account information.
Use the following code to add a <UserButton /> to your app:
import { UserButton } from "@clerk/nextjs";
export default function Home() {
return (
<div className="h-screen">
<UserButton />
</div>
)
}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.
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 application.
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