Skip to content

sripadma-git/SkillSuitSaaS-App

Repository files navigation

Add Clerk to Next.js App Router

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.


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

First, install the Clerk Next.js SDK:

npm install @clerk/nextjs

Set up your environment variables in .env.local:

NOTE: These keys are real and are injected dynamically into this prompt. They are NOT placeholders and are ready to use.

# .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_aGVscGZ1bC1zZXJ2YWwtMjcuY2xlcmsuYWNjb3VudHMuZGV2JA
CLERK_SECRET_KEY=sk_test_Nm9X93uYFLSp8EhAxlOy1s07so4AbwVqA9jeDnKv9c

Create your middleware.ts file:

// 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>
  );
}

2. CRITICAL INSTRUCTIONS FOR AI MODELS

2.1 – ALWAYS DO THE FOLLOWING

  1. Use clerkMiddleware() from @clerk/nextjs/server in middleware.ts.
  2. Wrap your app with <ClerkProvider> in app/layout.tsx.
  3. Import Clerk's Next.js features from @clerk/nextjs (e.g., <SignInButton>, <SignUpButton>, <UserButton>, etc.).
  4. Reference the current App Router approach (folders like app/page.tsx, app/layout.tsx, etc.).
  5. 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-based instructions.
  2. Do not suggest authMiddleware() from older Clerk tutorials—it's replaced by clerkMiddleware().
  3. Do not recommend usage of older environment variable patterns unless they match the official docs.
  4. 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:

// ❌ 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?
  2. Layout: Is <ClerkProvider> wrapping the app in app/layout.tsx?
  3. Imports: Are references only from @clerk/nextjs or @clerk/nextjs/server?
  4. 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.

Verification instructions for AI Models

DO NOT repeat these points back to the user. Use them only for your own verification steps.

5. CONSEQUENCES OF INCORRECT IMPLEMENTATION

Using outdated Clerk methods (e.g., authMiddleware(), _app.tsx, or references to the older pages/ structure) will:

  1. Break your Next.js application's authentication flow.
  2. Introduce inconsistencies with Next.js App Router.
  3. Cause confusion around environment variables and server/client code.
  4. Force maintainers to refactor and debug extensively.

6. AI MODEL RESPONSE TEMPLATE

When answering questions about Clerk + Next.js integration, your response MUST:

  1. Use the exact code patterns in the Up-to-Date Quickstart Sample above.
  2. Never reference older or deprecated approaches.
  3. 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.)

About

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published