Clerk + Next.js 15 in Production: The Gotchas Nobody Warns You About

The Clerk quickstart gives you one publishable key and one secret key. That works in development. The moment you deploy to Vercel with separate preview and production environments, you discover you need two publishable keys — one for development/preview instances and one for your production instance — and Next.js has no built-in way to swap NEXT_PUBLIC_ variables at runtime.

Our setup has a production Clerk instance (keyed off _live_) and a development instance. We broke auth in staging twice before we solved this with an explicit runtime check:

const isVercelProductionRuntime =
  process.env.NODE_ENV === 'production' && process.env.VERCEL_ENV === 'production'

const publishableKey = isVercelProductionRuntime
  ? process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PROD!
  : process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY!

The trap: VERCEL_ENV can be 'production' while NODE_ENV is technically 'production' during a preview build. Checking both guards against that edge case. We also added a fail-fast throw at startup if the wrong key appears in a production-only deployment — a wrong key fails silently at auth time, which is the worst possible moment to discover it.

Clerk supports a custom domain for its frontend API — clerk.yourdomain.com — which is what you want for production. During the transition from Clerk's shared CDN to your custom domain, if NEXT_PUBLIC_CLERK_FRONTEND_API_URL is set to the wrong value, OAuth flows silently stall after redirect without an error message.

Our fix: for live instances (key contains _live_), pass undefined for the frontend API and let Clerk resolve it automatically from the publishable key. For dev instances, read from the env var. Hardcoding the URL is not the right move — Clerk derives the correct endpoint from the key when you get out of its way.

If you have a Content-Security-Policy header on your site and you add Clerk without updating the CSP, auth will break in production in ways that look like network errors. Clerk loads scripts from its CDN, makes XHR calls to its API, and renders iframes for some flows — all of which need to be allowlisted.

The minimum additions to a tight CSP:

script-src: https://clerk.yourdomain.com https://cdn.jsdelivr.net
connect-src: https://clerk.yourdomain.com https://api.clerk.dev wss://clerk.yourdomain.com
frame-src: https://clerk.yourdomain.com https://accounts.google.com
img-src: https://img.clerk.com

If you use Clerk's hosted sign-in pages, also add the Clerk accounts domain to frame-ancestors. We caught this by watching the browser console for CSP violation reports, which appear as non-blocking warnings before they start silently killing auth flows when you tighten the policy.

Clerk's middleware documentation shows a broad matcher that protects everything. In a Next.js app with static assets, API routes, and public pages, a broad matcher adds latency to every request and can accidentally route static-file requests through Clerk's session validation.

Our matcher excludes the paths that should never touch auth:

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|logo|icons|og-image|sitemap|robots|ads.txt).*)',
  ],
}

The key exclusion is _next/static — without it, hot-module replacement in development goes through the auth middleware and slows every HMR update during development. More importantly, excluding known-public paths means search crawlers hitting your sitemap and robots.txt do not get bounced through a session check on every crawl.

When you configure a custom domain with Clerk, Clerk hosts an auth UI at clerk.yourdomain.com. This URL is publicly reachable, returns an HTML page, and has no noindex header — because it is Clerk's hosted page, not yours. Google will crawl it and may index it.

The indexed URL will show up in Search Console as "Page indexed without content" — because Google's crawler visits it, sees a Clerk auth form, and classifies it as a page with no meaningful content. This is not a problem you can fix in your codebase. The URL is served entirely by Clerk's infrastructure.

The two options are: submit a temporary removal request in Search Console (Removals → New Request → clerk.yourdomain.com) to deindex it, or accept it as a single low-impact entry that does not affect your content quality review. We went with the removal request to keep the index clean.

A minor but measurable optimization: we add both dns-prefetch and preconnect hints for the Clerk subdomain in the document head:

preconnect does the full TCP + TLS handshake early, which is right for the primary Clerk domain where auth calls happen. dns-prefetch is cheaper and sufficient for asset domains like the image CDN where the connection is not on the critical path. Using preconnect for everything wastes connections; using only dns-prefetch for the primary auth domain leaves latency on the table. Pick the right hint for the priority of the resource.

The most disruptive thing that can happen to a Clerk integration is a mismatch between your Convex deployment and your Clerk instance. Convex validates JWTs against the issuer URL embedded in the token. If your local dev server is pointed at the production Clerk instance but your Convex functions expect the development issuer, every authenticated query fails with a JWT validation error that looks like a network problem.

We added a startup assertion that throws fast if the wrong instance key is detected in a deployment that expects a specific instance. The error message names the detected key prefix and the expected one. A hard startup crash with a clear message beats a silent auth failure that wastes an hour of debugging.

If you customize Clerk's sign-in/sign-up modal via JavaScript (adding a logo, custom links, or a back button), you are racing against Clerk's own render. The modal is inserted into the DOM asynchronously after Clerk loads, and the timing is not deterministic.

The reliable pattern is a MutationObserver watching document.body for Clerk's card class to appear, combined with a short retry (100ms, 300ms, 600ms after detection). A one-shot setTimeout after page load misses the modal if Clerk loads slowly; polling on a fast interval wastes CPU. The observer gives you a near-instant callback when the modal appears, and the three short retries cover the gap between when Clerk inserts the container and when it finishes rendering the form inside it.