clerk · mwickett · May 13, 2025
@@ -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.
 </Steps>
 
+## 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 `<ClerkProvider>` in your `app/layout.tsx`
+- **Use** Clerk-provided components like `<SignInButton>`, `<SignUpButton>`, `<UserButton>`, `<SignedIn>`, `<SignedOut>` 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
+
+<Include src="_partials/nextjs/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 (
+    <ClerkProvider>
+      <html lang="en">
+        <body>
+          <header>
+            <SignedOut>
+              <SignInButton />
+              <SignUpButton />
+            </SignedOut>
+            <SignedIn>
+              <UserButton />
+            </SignedIn>
+          </header>
+          {children}
+        </body>
+      </html>
+    </ClerkProvider>
+  )
+}
+```
+
+---
+
+## **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 `<ClerkProvider>` in `app/layout.tsx`.
+1. **Import** Clerk’s Next.js features from `@clerk/nextjs` (e.g., `<SignInButton>`, `<SignUpButton>`, `<UserButton>`, 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 `<ClerkProvider>` 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
 
 <Include src="_partials/nextjs/next-steps" />