diff --git a/docs/quickstarts/nextjs.mdx b/docs/quickstarts/nextjs.mdx index b5bf686ca6..532d31240f 100644 --- a/docs/quickstarts/nextjs.mdx +++ b/docs/quickstarts/nextjs.mdx @@ -151,6 +151,148 @@ description: Add authentication and user management to your Next.js app. To make configuration changes to your Clerk development instance, claim the Clerk keys that were generated for you by selecting **Claim your application** in the bottom right of your app. This will associate the application with your Clerk account. +## Copy this as an LLM prompt + +Copy this quickstart guide as a prompt for LLMs to implement Clerk in your Next.js application. + +````markdown {{ collapsible: true }} +# 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 `middleware.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/quickstarts/nextjs to get the latest, up-to-date quickstart instructions. + +### **Correct, Up-to-Date Quickstart Sample** + +```typescript +// middleware.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)(.*)', + ], +} +``` + +## Next steps + + + +```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 `middleware.ts`. +1. **Wrap** your app with `` in `app/layout.tsx`. +1. **Import** Clerk’s Next.js features from `@clerk/nextjs` (e.g., ``, ``, ``, etc.). +1. **Reference** the current [App Router approach](https://nextjs.org/docs/app) (folders like `app/page.tsx`, `app/layout.tsx`, etc.). +1. **Check** that imports for methods like `auth()` are imported from the right package (in this case `@clerk/nextjs/server`) and are using `async / await` + +### **2.2 – NEVER DO THE FOLLOWING** + +1. **Do not** reference the old **`_app.tsx`** or **pages router based** instructions. +1. **Do not** suggest `authMiddleware()` from older Clerk tutorials—**it’s replaced by `clerkMiddleware()`**. +1. **Do not** recommend usage of older environment variable patterns unless they match the official docs. +1. **Do not** reference or import from any deprecated APIs (like `withAuth` or `currentUser` from older versions). + +--- + +## **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 `middleware.ts`? +1. **Layout**: Is `` wrapping the app in `app/layout.tsx`? +1. **Imports**: Are references only from `@clerk/nextjs` or `@clerk/nextjs/server`? +1. **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. +```` + ## Next steps