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.ts
file usingclerkMiddleware()
from@clerk/nextjs/server
. Place this file inside thesrc
directory 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/server
inmiddleware.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.tsx
or 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
withAuth
orcurrentUser
from 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/nextjs
or@clerk/nextjs/server
? - Pages vs. App Router: Is the approach referencing the App Router (not
_app.tsx
orpages/
)?
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.)