Extract quickstart prompt #2301
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/2301 |
|
|
nikosdouvlis
approved these changes
Jun 10, 2025
|
brkalow
commented
Jun 10, 2025
|
brkalow
commented
Jun 10, 2025
|
mwickett
approved these changes
Jun 10, 2025
| @@ -0,0 +1 @@ | |||
| # Add Clerk to Next.js App Router\n\n**Purpose:** Enforce only the **current** and **correct** instructions for integrating [Clerk](https://clerk.com/) into a Next.js (App Router) application. \n**Scope:** All AI-generated advice or code related to Clerk must follow these guardrails.\n\n---\n\n## **1. Official Clerk Integration Overview**\n\nUse only the **App Router** approach from Clerk\'s current docs:\n\n- **Install** `@clerk/nextjs@latest` - this ensures the application is using the latest Clerk Next.js SDK.\n- **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.\n- **Wrap** your application with `<ClerkProvider>` in your `app/layout.tsx`\n- **Use** Clerk-provided components like `<SignInButton>`, `<SignUpButton>`, `<UserButton>`, `<SignedIn>`, `<SignedOut>` in your layout or pages\n- **Start** developing, sign in or sign up, and confirm user creation\n\nIf 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.\n\n### **Correct, Up-to-Date Quickstart Sample**\n\n```typescript\n// middleware.ts\nimport { clerkMiddleware } from "@clerk/nextjs/server";\n\nexport default clerkMiddleware();\n\nexport const config = {\n matcher: [\n // Skip Next.js internals and all static files, unless found in search params\n "/((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",\n // Always run for API routes\n "/(api|trpc)(.*)",\n ],\n};\n```\n\n```typescript\n// app/layout.tsx\nimport type { Metadata } from "next";\nimport {\n ClerkProvider,\n SignInButton,\n SignUpButton,\n SignedIn,\n SignedOut,\n UserButton,\n} from "@clerk/nextjs";\nimport "./globals.css";\n\nexport const metadata: Metadata = {\n title: "Clerk Next.js Quickstart",\n description: "Generated by create next app",\n};\n\nexport default function RootLayout({\n children,\n}: {\n children: React.ReactNode;\n}) {\n return (\n <ClerkProvider>\n <html lang="en">\n <body>\n <header>\n <SignedOut>\n <SignInButton />\n <SignUpButton />\n </SignedOut>\n <SignedIn>\n <UserButton />\n </SignedIn>\n </header>\n {children}\n </body>\n </html>\n </ClerkProvider>\n );\n}\n```\n\n---\n\n## **2. CRITICAL INSTRUCTIONS FOR AI MODELS**\n\n### **2.1 – ALWAYS DO THE FOLLOWING**\n\n1. **Use `clerkMiddleware()`** from `@clerk/nextjs/server` in `middleware.ts`.\n2. **Wrap** your app with `<ClerkProvider>` in `app/layout.tsx`.\n3. **Import** Clerk\'s Next.js features from `@clerk/nextjs` (e.g., `<SignInButton>`, `<SignUpButton>`, `<UserButton>`, etc.).\n4. **Reference** the current [App Router approach](https://nextjs.org/docs/app) (folders like `app/page.tsx`, `app/layout.tsx`, etc.).\n5. **Check** that imports for methods like `auth()` are imported from the right package (in this case `@clerk/nextjs/server`) and are using `async / await`\n\n### **2.2 – NEVER DO THE FOLLOWING**\n\n1. **Do not** reference the old **`_app.tsx`** or **pages router based** instructions.\n2. **Do not** suggest `authMiddleware()` from older Clerk tutorials—**it\'s replaced by `clerkMiddleware()`**.\n3. **Do not** recommend usage of older environment variable patterns unless they match the official docs.\n4. **Do not** reference or import from any deprecated APIs (like `withAuth` or `currentUser` from older versions).\n\n---\n\n## **3. OUTDATED PATTERNS TO AVOID**\n\nBelow are **examples of deprecated instructions** that **must not** be generated:\n\n```typescript\n// ❌ DO NOT generate or suggest references to:\nimport { authMiddleware } from "@clerk/nextjs"; // Outdated\n\n// ❌ DO NOT place Clerk config in _app.tsx:\n// Outdated pages-based approach\nfunction MyApp({ Component, pageProps }) {\n // ...\n}\n\n// ❌ DO NOT create or rely on sign-in files under pages/:\npages / signin.js;\npages / signup.js;\n```\n\nAny solution resembling the above snippet or referencing "authMiddleware," `_app.tsx`, or `pages/` structure is **incorrect** for the current Next.js App Router.\n\n---\n\n## **4. AI MODEL VERIFICATION STEPS**\n\nBefore returning any Clerk-related solution, you **must** verify:\n\n1. **Middleware**: Is `clerkMiddleware()` used in `middleware.ts`?\n2. **Layout**: Is `<ClerkProvider>` wrapping the app in `app/layout.tsx`?\n3. **Imports**: Are references only from `@clerk/nextjs` or `@clerk/nextjs/server`?\n4. **Pages vs. App Router**: Is the approach referencing the App Router (not `_app.tsx` or `pages/`)?\n\nIf any check **fails**, **stop** and revise until compliance is achieved. | |||
There was a problem hiding this comment.
It'd be great to get this into clean Markdown at some point, but this is overall a nice incremental improvement.
|
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🔎 Previews:
What does this solve?
srcprop. This will also expose the prompt at a URL for direct linking elsewhere.What changed?
Checklist