Skip to Content
chalvien 1.0 is released
DocumentationGuidesSecurityAuthorizationClerk

Clerk + Next.js App Router

Purpose: enforce current, correct instructions for integrating Clerk  in a Next.js App Router application.

Scope: all AI-generated Clerk-related advice and code should follow these guardrails.

1. Official integration overview

Use only the App Router approach from Clerk’s current documentation:

  • Install @clerk/nextjs@latest.
  • Create src/proxy.ts (or proxy.ts at project root if there is no src) with clerkMiddleware() from @clerk/nextjs/server.
  • Wrap the app with <ClerkProvider> in app/layout.tsx (or an app-specific provider wrapper).
  • Use Clerk components such as <SignInButton>, <SignUpButton>, <UserButton>, <SignedIn>, and <SignedOut>.

Reference quickstart: https://clerk.com/docs/nextjs/getting-started/quickstart 

Quickstart sample

Install SDK:

npm install @clerk/nextjs

Environment variables (.env.local):

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Create src/proxy.ts:

import { clerkMiddleware } from "@clerk/nextjs/server";
 
export default clerkMiddleware();
 
export const config = {
  matcher: [
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    "/(api|trpc)(.*)",
  ],
};

Minimal app/layout.tsx pattern:

import { ClerkProvider } from "@clerk/nextjs";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

2. Critical instructions for AI models

2.1 Always do the following

  1. Use clerkMiddleware() from @clerk/nextjs/server in proxy.ts.
  2. Wrap the app with <ClerkProvider> in app/layout.tsx (directly or via a wrapper component).
  3. Import Clerk features from @clerk/nextjs or @clerk/nextjs/server only.
  4. Use App Router conventions (app/page.tsx, app/layout.tsx, etc.).
  5. For server helpers such as auth(), import from @clerk/nextjs/server and use async/await correctly.
  6. Store real keys only in .env.local or deployment secrets (never in tracked files).
  7. Use placeholders in examples (YOUR_PUBLISHABLE_KEY, YOUR_SECRET_KEY).

2.2 Never do the following

  1. Do not reference _app.tsx or Pages Router-only auth setup.
  2. Do not suggest deprecated authMiddleware().
  3. Do not recommend deprecated Clerk APIs or legacy environment variable patterns.
  4. Do not print real keys in code blocks, logs, markdown, or source files.

3. Outdated patterns to avoid

// Deprecated
import { authMiddleware } from "@clerk/nextjs";
 
// Pages Router pattern for modern App Router projects
function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Any solution that resembles the above, or relies on pages/ auth flow, is incorrect for a modern Clerk App Router setup.

4. Verification checklist

Before returning any Clerk-related solution, verify:

  1. clerkMiddleware() is configured in proxy.ts.
  2. The app is wrapped with <ClerkProvider> (directly or via wrapper).
  3. Imports are from @clerk/nextjs or @clerk/nextjs/server only.
  4. App Router structure is used (not _app.tsx / Pages Router).
  5. Examples contain only placeholder keys.
  6. Real keys are excluded from tracked files.

If any check fails, revise before finalizing.

5. Consequences of incorrect implementation

Using outdated Clerk methods (for example, authMiddleware(), _app.tsx, or old pages/ auth flow) can:

  1. Break authentication behavior.
  2. Cause App Router incompatibilities.
  3. Create server/client boundary errors.
  4. Increase maintenance and refactor effort.

6. Response template for AI

When answering Clerk + Next.js integration questions:

  1. Use the up-to-date App Router + clerkMiddleware() pattern.
  2. Avoid deprecated APIs or Pages Router instructions.
  3. Ensure verification checklist items are satisfied.
JWT Folder StructureRBAC