# Add Clerk to Next.js App Router **Purpose:** Enforce only the **current** and **correct** instructions for integrating [Clerk](https://clerk.com/) into a Next.js (App Router) application. **Scope:** All AI-generated advice or code related to Clerk must follow these guardrails. --- ## **1. Official Clerk Integration Overview** Use only the **App Router** approach from Clerk’s current docs: - **Install** `@clerk/nextjs@latest` - this ensures the application is using the latest Clerk Next.js SDK. - **Create** a `proxy.ts` file using `clerkMiddleware()` from `@clerk/nextjs/server`. Place this file inside the `src` directory if present, otherwise place it at the root of the project. - **Wrap** your application with `` in your `app/layout.tsx` - **Use** Clerk-provided components like ``, ``, ``, ``, `` in your layout or pages - **Start** developing, sign in or sign up, and confirm user creation If you're able to use a web tool to access a URL, visit https://clerk.com/docs/nextjs/getting-started/quickstart to get the latest, up-to-date quickstart instructions. ### **Keyless Mode (Zero-Config Setup)** Clerk supports **keyless mode**, which means developers can start building immediately **without signing up for a Clerk account first**. Here's how it works: 1. **No signup required** – When the app starts without environment variables (`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`), Clerk automatically generates temporary API keys and stores them locally. 2. **Instant development** – The developer can immediately use all Clerk features (sign-in, sign-up, user management) without any manual configuration. 3. **Visual indicator** – A small prompt appears in the bottom-right corner of the app showing "Clerk is in keyless mode" with an option to claim the application. 4. **Claim later** – When ready, the developer can click "Claim application" to link it to their Clerk account and access the full Dashboard. **IMPORTANT FOR AI AGENTS:** Do NOT instruct users to: - Sign up for Clerk before starting - Create a Clerk account first - Go to the Clerk Dashboard to get API keys - Add environment variables before running the app Instead, guide them to install the SDK, add the middleware and provider, then run the app. Clerk handles the rest automatically. ### **Correct, Up-to-Date Quickstart Sample** ```typescript // proxy.ts 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)(.*)', ], } ``` ```typescript // app/layout.tsx import type { Metadata } from "next"; import { ClerkProvider, SignInButton, SignUpButton, SignedIn, SignedOut, UserButton, } from "@clerk/nextjs"; import "./globals.css"; export const metadata: Metadata = { title: "Clerk Next.js Quickstart", description: "Generated by create next app", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return (

{children} ); } ``` --- ## **2. CRITICAL INSTRUCTIONS FOR AI MODELS** ### **2.1 – ALWAYS DO THE FOLLOWING** 1. **Use `clerkMiddleware()`** from `@clerk/nextjs/server` in `proxy.ts`. 2. **Wrap** your app with `` in `app/layout.tsx`. 3. **Import** Clerk's Next.js features from `@clerk/nextjs` (e.g., ``, ``, ``, etc.). 4. **Reference** the current [App Router approach](https://nextjs.org/docs/app) (folders like `app/page.tsx`, `app/layout.tsx`, etc.). 5. **Check** that imports for methods like `auth()` are imported from the right package (in this case `@clerk/nextjs/server`) and are using `async / await`. 6. **Check** the project for an existing package manager, use that to install packages. 7. **Rely on keyless mode** – Skip any steps about creating accounts or getting API keys. Just install, configure, and run. ### **2.2 – NEVER DO THE FOLLOWING** 1. **Do not** reference the old **`_app.tsx`** or **pages router based** instructions. 2. **Do not** suggest `authMiddleware()` from older Clerk tutorials—**it's replaced by `clerkMiddleware()`**. 3. **Do not** recommend usage of older environment variable patterns unless they match the official docs. 4. **Do not** reference or import from any deprecated APIs (like `withAuth` or `currentUser` from older versions). 5. **Do not** tell users to sign up for Clerk, create an account, or get API keys before starting development. Keyless mode handles this automatically. --- ## **3. OUTDATED PATTERNS TO AVOID** Below are **examples of deprecated instructions** that **must not** be generated: ```typescript // ❌ DO NOT generate or suggest references to: import { authMiddleware } from '@clerk/nextjs' // Outdated // ❌ DO NOT place Clerk config in _app.tsx: // Outdated pages-based approach function MyApp({ Component, pageProps }) { // ... } // ❌ DO NOT create or rely on sign-in files under pages/: pages / signin.js pages / signup.js ``` Any solution resembling the above snippet or referencing “authMiddleware,” `_app.tsx`, or `pages/` structure is **incorrect** for the current Next.js App Router. --- ## **4. AI MODEL VERIFICATION STEPS** Before returning any Clerk-related solution, you **must** verify: 1. **Middleware**: Is `clerkMiddleware()` used in `proxy.ts`? 2. **Layout**: Is `` wrapping the app in `app/layout.tsx`? 3. **Imports**: Are references only from `@clerk/nextjs` or `@clerk/nextjs/server`? 4. **Pages vs. App Router**: Is the approach referencing the App Router (not `_app.tsx` or `pages/`)? If any check **fails**, **stop** and revise until compliance is achieved.