@clerk/nextjs

# @clerk/nextjs

Hosted auth for Next.js App Router: sign-up, sign-in, sessions, user management, organizations, billing. Your app never stores passwords.

## Install

```bash
npm install @clerk/nextjs
```

## Keys (pick one)

```bash
npx clerk@latest init          # temporary dev keys, no account needed, writes .env.local
```

Or create an app at https://dashboard.clerk.com/~/api-keys and set in `.env.local`:

```
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
```

Without keys, pages that call Clerk fail at request time. `next build` can pass without them, so do not treat a green build as proof the app works.

## Protect routes

Next.js 16 uses `proxy.ts`; Next.js 15 and earlier use `middleware.ts`. Place it in `src/` if the app uses `src/`.

```ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtected = createRouteMatcher(['/dashboard(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isProtected(req)) await auth.protect()
})

export const config = {
  matcher: ['/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', '/(api|trpc)(.*)'],
}
```

Wrap the app in `app/layout.tsx`:

```tsx
import { ClerkProvider } from '@clerk/nextjs'
// <html><body><ClerkProvider>{children}</ClerkProvider></body></html>
```

Sign-in page at `app/sign-in/[[...sign-in]]/page.tsx`: `import { SignIn } from '@clerk/nextjs'` and render `<SignIn />`. Same for `SignUp`. Use `<UserButton />` for sign-out.

Server-side user: `const { userId } = await auth()` from `@clerk/nextjs/server` (async).

## For AI agents

- Docs as markdown: https://clerk.com/docs/nextjs/getting-started/quickstart.md
- Search: https://clerk.com/docs/search.md?q=<query>&sdk=nextjs
- Index: https://clerk.com/llms.txt
- Skill: https://clerk.com/SKILL.md · MCP: https://mcp.clerk.com/mcp
- Accountless keys: https://clerk.com/auth.md

# Clerk in a Next.js App Router app

Consumer instructions. (Monorepo contributors: use the root AGENTS.md instead.)

## Install

Use the project's existing package manager (check the lockfile). Do not add a second lockfile.

```bash
npm install @clerk/nextjs
```

Do not upgrade next or react unless `npm install` reports a peer-dependency error.

## Env vars (`.env.local`)

- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` (pk_test_...)
- `CLERK_SECRET_KEY` (sk_test_...)
- `NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in`, `NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up`

Get keys with no account via `npx clerk@latest init` (or https://clerk.com/auth.md), otherwise from https://dashboard.clerk.com/~/api-keys. Never invent keys. Commit `.env.example` with empty values and keep `.env.local` out of git.

## The one code path

1. `src/proxy.ts` (Next 16) or `src/middleware.ts` (Next 15 and earlier): `export default clerkMiddleware(...)` from `@clerk/nextjs/server`; call `await auth.protect()` for routes matched by `createRouteMatcher(['/dashboard(.*)'])`.
2. `app/layout.tsx`: wrap `{children}` in `<ClerkProvider>` from `@clerk/nextjs`.
3. `app/sign-in/[[...sign-in]]/page.tsx` renders `<SignIn />`; sign-up renders `<SignUp />`.
4. Server code: `const { userId } = await auth()` from `@clerk/nextjs/server`.

## Mistakes agents make

1. Writing `middleware.ts` on Next 16, or `proxy.ts` on Next 15. Check the installed next version.
2. Calling `auth()` without `await`, or importing server helpers from `@clerk/nextjs` instead of `@clerk/nextjs/server`.
3. Using the removed `authMiddleware`, or declaring success on a green build. Without real keys every request returns a 500 and sign-in is untested.

## Verify

```bash
npm run build
npm run dev & sleep 5; curl -sI localhost:3000/dashboard   # expect a 307 to sign-in or Clerk handshake
```

With real keys, sign up in a browser and confirm /dashboard loads. Tell the user what was and was not tested.

Docs: https://clerk.com/docs/nextjs/getting-started/quickstart.md

{
  "description": "Hosted authentication for Next.js App Router: sign-up, sign-in, sessions, Google/GitHub social login, user management, organizations and subscription billing. No password handling in your app.",
  "keywords": ["clerk", "nextjs", "next.js", "app-router", "auth", "authentication", "login", "sign-in", "sign-up", "oauth", "google", "github", "social-login", "session", "jwt", "middleware", "proxy", "mfa", "passwordless", "billing", "subscriptions", "hosted-auth"],
  "homepage": "https://clerk.com/docs/nextjs/getting-started/quickstart",
  "files": ["dist", "README.md", "AGENTS.md"]
}