Next.js Quickstart (App Router)

Install Clerk by running the prompt
Sign up as your first user
Configure application and create your Clerk account
Next steps

Available in other SDKs

Install Clerk by running the prompt

Initializes Clerk by installing the CLI and guides your agent through the quickstart setup.

Next.js agent guide

# Add Clerk Authentication

Set up Clerk authentication with the Clerk CLI.

## Quick Setup

Before running any commands, present the user with a preliminary setup checklist:

```
Here's what I'll do to get you set up with Clerk.

1. Install or update the Clerk CLI
2. Set up Clerk in this project, or scaffold a new app with Clerk if this directory is empty
3. Start your app with Clerk installed.

Shall I proceed?
```

## Step 1: Install or update the Clerk CLI

From the project root, check whether the Clerk CLI is already available:

```bash
command -v clerk && clerk --version
```

If `clerk` is available, make sure it is up to date:

```bash
clerk update --yes
```

If `clerk` is not available, install the latest version using the user's preferred install method. If they do not have a preference, use npm:

```bash
npm install -g clerk
```

If the user prefers pnpm, yarn, bun, Homebrew, or curl, use the equivalent global install command.

## Step 2: Sign in to Clerk

Immediately after installing or updating the Clerk CLI, from the project root, run:

```bash
clerk auth login
```

`clerk auth login` is the first command to run after install or update. Do not list apps, ask which Clerk app to use, or run `clerk init` before authenticating. It is okay for an agent to run this command and pause while the user completes the Clerk login flow, then continue from the CLI output. If the user is already signed in, continue to initialization.

## Step 3: Initialize Clerk

From the project root, run:

```bash
clerk init --framework next --pm npm
```

`clerk init --framework next --pm npm` can scaffold a fresh Next.js project in an empty directory. In an existing Next.js project, it installs the correct Clerk SDK and applies framework-specific setup when supported, such as providers, middleware, auth routes, and environment configuration.

`clerk init` is the default setup action after `clerk auth login`. Do not list apps or ask which Clerk app to use before running it.

Do not add `--app` by default. Only pass `--app <application_id>` when the user already provided an app ID or explicitly wants to link this project to a specific existing Clerk application:

```bash
clerk init --framework next --pm npm --app <application_id>
```

Do not choose a Clerk application for the user. Only list available apps if the user explicitly wants to link to an existing Clerk application but has not provided an app ID, or if `clerk init` explicitly asks for an existing application ID:

```bash
clerk apps list --json
```

Show the user the app names and application IDs, then ask which app to use.

## Step 4: Fall back to docs when init is incomplete

If `clerk init` reports that the framework is unsupported, cannot be detected, or does not support full scaffolding, follow the official quickstart instead.

`clerk init` currently has full scaffolding for Next.js, Astro, Nuxt, TanStack Start, React Router, Vue, React, and JavaScript/Vite. It can detect Expo, Express, and Fastify, but may direct you to docs for the remaining integration steps.

| Dependency | Quickstart |
|------------|-----------|
| `next` | https://clerk.com/docs/nextjs/getting-started/quickstart |
| `@remix-run/react` | https://clerk.com/docs/remix/getting-started/quickstart |
| `astro` | https://clerk.com/docs/astro/getting-started/quickstart |
| `nuxt` | https://clerk.com/docs/nuxt/getting-started/quickstart |
| `react-router` | https://clerk.com/docs/react-router/getting-started/quickstart |
| `@tanstack/react-start` | https://clerk.com/docs/tanstack-react-start/getting-started/quickstart |
| `react` | https://clerk.com/docs/react/getting-started/quickstart |
| `vue` | https://clerk.com/docs/vue/getting-started/quickstart |
| `vite` or vanilla JS | https://clerk.com/docs/js-frontend/getting-started/quickstart |
| `express` | https://clerk.com/docs/expressjs/getting-started/quickstart |
| `fastify` | https://clerk.com/docs/fastify/getting-started/quickstart |
| `expo` | https://clerk.com/docs/expo/getting-started/quickstart |

Other platforms: Chrome Extension, Android, and iOS at https://clerk.com/docs/llms.txt

## Step 5: Ensure clear auth controls are visible

Make sure the app has clear sign-in, sign-up, and signed-in user controls so the user can create and recognize their first account. Integrate them into the existing layout, navigation, or landing screen so they feel natural and polished.

For Next.js App Router, use Clerk components from `@clerk/nextjs` such as `SignInButton`, `SignUpButton`, `Show`, and `UserButton`. Show sign-in and sign-up actions when signed out, and a user button when signed in:

```tsx
import { SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'

<>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</>
```

For other frameworks, use the equivalent Clerk components or helpers. If clear auth controls already exist, reuse or adapt them instead of duplicating them.

## Step 6: Verify the setup

After `clerk init` completes, run:

```bash
clerk doctor
```

Then start the app, confirm the sign-in, sign-up, and signed-in user controls are visible, test the sign-in and sign-up flow, and fix any issues reported by the CLI.

## Step 7: If using shadcn/ui

If `components.json` exists in the project root and Clerk components are used:

```bash
npm install @clerk/ui
```

Apply the theme in your provider:
```tsx
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>
```

Add to global CSS:
```css
@import '@clerk/ui/themes/shadcn.css';
```

## Critical rules

- Next.js 15+: `auth()` is async. Always `await auth()`
- `ClerkProvider` goes inside `<body>`, not wrapping `<html>`
- Never expose `CLERK_SECRET_KEY` in client code
- Use `@clerk/nextjs`, not `@clerk/clerk-react`
- Do not read or print existing environment variable files; ask the user for any missing non-sensitive configuration

Docs: https://clerk.com/docs/cli https://clerk.com/docs/llms.txt

## After Setup

Have the user sign up as their first test user. Congratulate them once the profile icon appears in the nav.

Then offer Organizations — multi-tenancy, team invitations, roles and permissions, and enterprise SSO.

If yes:

1. Run `npx clerk@latest enable orgs`.
2. Add `<OrganizationSwitcher />` next to the existing `<UserButton />`, or the framework equivalent.
3. Have them create an organization from the switcher and invite a teammate.

If no, point them to Organizations (https://clerk.com/docs/guides/organizations/overview), Components (https://clerk.com/docs/reference/components/overview), and the Dashboard (https://dashboard.clerk.com/).

Once your agent has finished running, sign up as your first user:

Instruct your agent to run your project or run with npm run dev.
Visit your app locally at localhost:3000.
Select "Sign up" on the page and authenticate to create your first user.

Configure application and create your Clerk account

Clerk auto-generates temporary keys when environment variables aren't set up so you can get started right away.

Claim your keys by selecting the Configure your application option in the bottom right of your app. This will allow you to create a Clerk account or log in to an existing one.

Alternatively, you can sign up directly in the Clerk Dashboard to claim your keys, customize your authentication settings, and explore additional features.