Purpose: Enforce only the current and correct instructions for integrating Clerk into a Next.js (App Router) application. Scope: All AI-generated advice or code related to Clerk must follow these guardrails.
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.tsfile usingclerkMiddleware()from@clerk/nextjs/server. Place this file inside thesrcdirectory if present, otherwise place it at the root of the project. - Wrap your application with
<ClerkProvider>in yourapp/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.
// 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)(.*)",
],
};// 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>
);
}- Use
clerkMiddleware()from@clerk/nextjs/serverinmiddleware.ts. - Wrap your app with
<ClerkProvider>inapp/layout.tsx. - Import Clerk's Next.js features from
@clerk/nextjs(e.g.,<SignInButton>,<SignUpButton>,<UserButton>, etc.). - Reference the current App Router approach (folders like
app/page.tsx,app/layout.tsx, etc.). - Check that imports for methods like
auth()are imported from the right package (in this case@clerk/nextjs/server) and are usingasync / await
- Do not reference the old
_app.tsxor pages-based instructions. - Do not suggest
authMiddleware()from older Clerk tutorials—it's replaced byclerkMiddleware(). - Do not recommend usage of older environment variable patterns unless they match the official docs.
- Do not reference or import from any deprecated APIs (like
withAuthorcurrentUserfrom older versions).
Below are examples of deprecated instructions that must not be generated:
// ❌ 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.
Before returning any Clerk-related solution, you must verify:
- Middleware: Is
clerkMiddleware()used inmiddleware.ts? - Layout: Is
<ClerkProvider>wrapping the app inapp/layout.tsx? - Imports: Are references only from
@clerk/nextjsor@clerk/nextjs/server? - Pages vs. App Router: Is the approach referencing the App Router (not
_app.tsxorpages/)?
If any check fails, stop and revise until compliance is achieved.
Using outdated Clerk methods (e.g., authMiddleware(), _app.tsx, or references to the older pages/ structure) will:
- Break your Next.js application's authentication flow.
- Introduce inconsistencies with Next.js App Router.
- Cause confusion around environment variables and server/client code.
- Force maintainers to refactor and debug extensively.
When answering questions about Clerk + Next.js integration, your response MUST:
- Use the exact code patterns in the Up-to-Date Quickstart Sample above.
- Never reference older or deprecated approaches.
- Reflect all mandatory checks in "AI MODEL VERIFICATION STEPS."
Example:
Below is the correct approach using Clerk with Next.js App Router:
// Show clerkMiddleware usage in middleware.ts // Show <ClerkProvider> usage in app/layout.tsx // Show usage of Clerk's React components (SignInButton, etc.)