# Next.js Quickstart (App Router)

> This is the default quickstart for new Next.js apps. If you're using Pages Router, follow the [Pages Router quickstart](https://clerk.com/docs/getting-started/quickstart/pages-router.md?sdk=nextjs) instead.

1. ## Create a new Next.js app

   If you don't already have a Next.js app, run the following commands to [create a new one](https://nextjs.org/docs/getting-started/installation).

   ```npm
   npm create next-app@latest clerk-nextjs -- --yes
   cd clerk-nextjs
   ```
2. ## Install `@clerk/nextjs`

   The [Clerk Next.js SDK](https://clerk.com/docs/nextjs/reference/overview.md) gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

   Run the following command to install the SDK:

   ```npm
   npm install @clerk/nextjs
   ```
3. ## Set your Clerk API keys

   Add the following keys to your `.env` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard.

   If you haven't already, create a new Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md?sdk=nextjs).

   1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/~/api-keys) page.
   2. In the **Quick Copy** section, copy your Clerk Publishable Key and Secret Key.
   3. Paste your keys into your `.env` file.

   The final result should resemble the following:

   filename: .env

   ```env
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}}
   CLERK_SECRET_KEY={{secret}}
   ```
4. ## Add `clerkMiddleware()` to your app

   [clerkMiddleware()](https://clerk.com/docs/nextjs/reference/clerk-middleware.md) grants you access to user authentication state throughout your app. To add `clerkMiddleware()` to your app, follow these steps:

   > If you're using Next.js ≤15, name your file `middleware.ts` instead of `proxy.ts`. The code itself remains the same; only the filename changes.

   1. Create a `proxy.ts` file.

      - If you're using the `/src` directory, create `proxy.ts` in the `/src` directory.
      - If you're not using the `/src` directory, create `proxy.ts` in the root directory.

   2. In your `proxy.ts` file, export the `clerkMiddleware()` helper:

      filename: proxy.ts

      ```tsx
      import { clerkMiddleware } from '@clerk/nextjs/server'

      export default clerkMiddleware()

      export const config = {
        matcher: [
          // Skip Next.js internals and all static files, unless found in search params
          '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
          // Always run for API routes
          '/(api|trpc)(.*)',
          // Always run for Clerk-specific frontend API routes
          '/__clerk/(.*)',
        ],
      }
      ```

   3. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection. To require a signed-in user, protect resources close to where they're used, as shown in the [guide on protecting content](https://clerk.com/docs/nextjs/guides/secure/protect-content.md).
5. ## Add `<ClerkProvider>` and Clerk components to your app

   The [<ClerkProvider>](https://clerk.com/docs/nextjs/reference/components/clerk-provider.md) 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](https://clerk.com/docs/nextjs/reference/components/clerk-provider.md) for other configuration options.

   Copy and paste the following code into your `layout.tsx` file. This:

   - Adds the `<ClerkProvider>` component to your app's layout, providing Clerk's authentication context to your app.
   - Creates a header with Clerk's [prebuilt components](https://clerk.com/docs/nextjs/reference/components/overview.md) to allow users to sign in and out, and display different content for signed-in and signed-out users.

   filename: app/layout.tsx

   ```tsx
   import type { Metadata } from 'next'
   import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from '@clerk/nextjs'
   import { Geist, Geist_Mono } from 'next/font/google'
   import './globals.css'

   const geistSans = Geist({
     variable: '--font-geist-sans',
     subsets: ['latin'],
   })

   const geistMono = Geist_Mono({
     variable: '--font-geist-mono',
     subsets: ['latin'],
   })

   export const metadata: Metadata = {
     title: 'Clerk Next.js Quickstart',
     description: 'Generated by create next app',
   }

   export default function RootLayout({
     children,
   }: Readonly<{
     children: React.ReactNode
   }>) {
     return (
       <html lang="en" className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}>
         <body className="min-h-full flex flex-col">
           <ClerkProvider>
             <header className="flex justify-end items-center p-4 gap-4 h-16">
               <Show when="signed-out">
                 <SignInButton />
                 <SignUpButton>
                   <button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
                     Sign Up
                   </button>
                 </SignUpButton>
               </Show>
               <Show when="signed-in">
                 <UserButton />
               </Show>
             </header>
             {children}
           </ClerkProvider>
         </body>
       </html>
     )
   }
   ```

   This example uses the following components:

   - [<Show when="signed-in">](https://clerk.com/docs/nextjs/reference/components/control/show.md): Children of this component can only be seen while **signed in**.
   - [<Show when="signed-out">](https://clerk.com/docs/nextjs/reference/components/control/show.md): Children of this component can only be seen while **signed out**.
   - [<UserButton />](https://clerk.com/docs/nextjs/reference/components/user/user-button.md): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
   - [<SignInButton />](https://clerk.com/docs/nextjs/reference/components/unstyled/sign-in-button.md): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=nextjs) are set for the sign-in URL, this component links to the [Account Portal sign-in page](https://clerk.com/docs/guides/account-portal/overview.md?sdk=nextjs#sign-in).
   - [<SignUpButton />](https://clerk.com/docs/nextjs/reference/components/unstyled/sign-up-button.md): An unstyled component that links to the sign-up page. In this example, since no props or [environment variables](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=nextjs) are set for the sign-up URL, this component links to the [Account Portal sign-up page](https://clerk.com/docs/guides/account-portal/overview.md?sdk=nextjs#sign-up).
6. ## Run your project

   Run your project with the following command:

   ```npm
   npm run dev
   ```
7. ## Create your first user

   1. Visit your app's homepage at http://localhost:3000.
   2. Select "Sign up" on the page and authenticate to create your first user.

## Next steps

Explore the most relevant next steps for your SDK using the following guides.

- [Prebuilt components](https://clerk.com/docs/reference/components/overview.md?sdk=nextjs): Learn how to add Clerk's prebuilt authentication and user-management UI to your app.
- [Build custom flows](https://clerk.com/docs/guides/development/custom-flows/overview.md?sdk=nextjs): Learn how to build custom user interfaces entirely from scratch using the Clerk API.
- [Read user data](https://clerk.com/docs/guides/users/reading.md?sdk=nextjs): Learn how to use Clerk's helpers to read user data in your app.
- [Customization & localization](https://clerk.com/docs/guides/customizing-clerk/appearance-prop/overview.md?sdk=nextjs): Learn how to customize and localize Clerk components.

## More to explore

Explore additional Clerk features that help you build, manage, and grow your application.

- [**Organizations**](https://clerk.com/docs/guides/organizations/overview.md?sdk=nextjs) - Organizations are shared accounts that let teams collaborate, manage members and roles, and control access to shared resources.
- [**Billing**](https://clerk.com/docs/guides/billing/overview.md?sdk=nextjs) - Billing enables you to manage subscriptions, free trials, payments, plans, and billing-related webhook events for B2C and B2B applications.
- [**Waitlist**](https://clerk.com/docs/guides/secure/restricting-access.md?sdk=nextjs#waitlist) - Waitlist lets you collect signups and control access to new products or features before launch through a simple, integrated workflow.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)