docs: document vercel.app production support

[Railly]

Previews

• https://clerk.com/docs/pr/railly-aie-933-vercel-app-production-docs/guides/development/deployment/production
• https://clerk.com/docs/pr/railly-aie-933-vercel-app-production-docs/guides/development/deployment/vercel
• https://clerk.com/docs/pr/railly-aie-933-vercel-app-production-docs/guides/development/integrations/platforms/vercel-marketplace

Summary

Documents *.vercel.app production domain support for Clerk apps.

This updates the deployment docs so they no longer say Vercel-provided *.vercel.app domains cannot be used for production, and clarifies the supported behavior, limitations, Vercel Marketplace production-domain behavior, and Next.js proxy matcher requirement.

Related PRs / landing order

These PRs are part of the *.vercel.app production support launch batch:

1. clerk_go AIE-934 - clerk/clerk_go#18546 - merged; removes the per-instance email flag and keeps the global kill switch as the rollout control.
2. clerk_go AIE-932 - clerk/clerk_go#18547 - merged; allows DAPI production instance creation with *.vercel.app provider domains.
3. clerk_go AIE-955 - clerk/clerk_go#18749 - merged; disables Account Portal by default for *.vercel.app provider-domain production apps.
4. dashboard AIE-932 - clerk/dashboard#9184 - merged; allows the Dashboard production instance modal to submit my-app.vercel.app and exposes proxy setup/verification guidance.
5. clerk-docs AIE-933 - this PR - documents support, limitations, Vercel Marketplace production-domain behavior, and the Next.js /__clerk matcher requirement.

Recommended order: publish these docs after the Dashboard behavior is ready to launch.

Changes

• Update Vercel deployment docs to document *.vercel.app production support.
• Replace the old quiz that said *.vercel.app production domains were unsupported.
• Update production deployment docs to distinguish custom-domain production from Vercel provider-domain production.
• Document supported behavior: production mode, no manual DNS, sign-in/sign-up, and core auth emails through accounts.dev.
• Document limitations that require a custom domain: custom email templates, email link auth, app invitations, organization invitations, email template customization, and hosted Account Portal.
• Add Vercel Marketplace production-domain guidance for *.vercel.app domains.
• Add the Next.js matcher requirement so auto-proxy traffic through /__clerk is not excluded.
• Add Dashboard Verify proxy guidance and troubleshooting notes for live keys, domain sync, old SDKs, and missing matcher configuration.

Test plan

• pnpm prettier --check docs/guides/development/deployment/vercel.mdx docs/guides/development/deployment/production.mdx docs/guides/development/integrations/platforms/vercel-marketplace.mdx

Known local limitation: full docs build is blocked in my local checkout by an unrelated untracked file, docs/guides/ai/clerk-cli.mdx, which is not in the docs manifest.

Linear: AIE-933

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jul 24, 2026 10:12pm

[manovotny]

Pushed some polish directly in 409bfe8.

• Tightened the SDK guidance with concrete version floors (@clerk/nextjs 7.2.8+, @clerk/clerk-js 6.7.8+, @clerk/backend 3.4.2+) in both spots of production.mdx. The previous wording — "a Clerk SDK version that supports Vercel auto-proxy" — left readers without a way to actually verify their install.
• Switched "Next.js middleware or proxy" to "Next.js proxy" across all three files to match how the rest of the docs treat the Next.js 16 rename, set the filename annotation on the code block to proxy.ts, and dropped in the existing _partials/nextjs/nextjs-15-callout partial after it.
• Linked the Domains Dashboard reference and rewrote "After configuring" → "After you configure" for active voice (production.mdx, vercel.mdx).
• "Make sure" → "Ensure" per the styleguide (vercel.mdx, vercel-marketplace.mdx).
• "application invitations" → "Application invitations" in vercel-marketplace.mdx to match the casing the other two files already use.

Follow-up in f80a2ab:

• Linked the "email feature limitations" mention in the "Before you begin" section to the *.vercel.app production domains section, and added an explicit {{ id: 'vercel-app-production-domains' }} to that heading so the anchor stays stable.

Let me know if I got anything wrong, especially the SDK frameworks and versions.

[Railly]

@manovotny looks right to me. I verified the minimum auto-proxy floors against the JS changelogs: @clerk/nextjs 7.2.8, @clerk/clerk-js 6.7.8, and @clerk/backend 3.4.2 all include the .vercel.app auto-proxy change.

Only nuance: for Next.js we had discussed 7.3.1+ as the safer recommendation because it pulls @clerk/shared 4.10.0 with the follow-up guard for runtimes where process is unavailable. But as minimum versions for auto-proxy support, the numbers you added are accurate.

[Railly]

Good call @manovotny, addressed all of these in d36cee0.

• aligned the matcher guidance with Dashboard
• removed the duplicate email-template limitation
• switched the single-column table to bullets
• tightened the Vercel env sync wording to avoid implying prod keys are synced automatically.

[Railly]

@alexisintech @manovotny, pushed e0e34ca4 adding three new subsections to production.mdx based on smoke findings against a real *.vercel.app production instance: vanilla components vs override surfaces (Account Portal disabled), session-token iss claim for external verifiers, and custom OAuth provider callback URL. Also added two troubleshooting bullets pointing into them.

Could I get a re-review on the new content? Rest of the PR is unchanged from your last pass.

[manovotny]

Took a pass at restructuring the page to reduce custom-domain vs. vercel.app zig-zag — landed in three commits.

28b75b2 restructure production guide to reduce domain-path zig-zag

• Replaced the two scattered domain-specific H2s with a single ## Configure your domain H2 housing both as sibling H3s, removing the "skip this section" cross-link.
• Tightened "Before you start" (begin → start to match repo convention), folded the DNS-records-access prereq into the Custom domain section where it belongs.
• Added an *.vercel.app callback-URL forward-pointer in ## OAuth credentials.
• Added an applicability note on ## Authentication across subdomains (custom-domain-only — vercel.app is on the Public Suffix List, so the sibling-cookie sharing doesn't apply).
• Reordered troubleshooting bullets to cluster by path (custom-domain entries first, then vercel.app, then common).

d594e0f lighten vercel app sub-sections and reposition callouts

• Lifted the feature comparison table up to ## Configure your domain — it's decision-helping content, so it now sits before the reader commits to a path, not buried inside the Vercel branch.
• Rewrote the Authentication on the app domain content from two dense tables to prose + code examples, splitting the helper-vs-component conflation into clearly named subsections ("Components in navigation mode" / "Standalone redirect helpers"). This also resolves the pending review thread about clerk.redirectToUserProfile() not being override-able via props.
• Moved the SDK version requirement to a NOTE callout (after the intro paragraph), dropped the redundant pk_live_ bullet (covered by ## API keys and environment variables upstream), and demoted the 48hrs DNS propagation note from a NOTE callout to plain prose — three callouts in succession was diluting their attention-grabbing purpose.

9046365 switch domain paths to Tabs and promote sub-headings

• Replaced the two H3 paths with <Tabs items={["Custom domain", "Vercel *.vercel.app domain"]}>, since the comparison table above already makes the choice explicit and tabs are a cleaner visual picker.
• Promoted everything one heading level inside the Vercel tab: H4s → H3s (now in the TOC), H5s → H4s (now styled — H5 has no typography rules in clerk/clerk and rendered as bare text).
• Updated proxy-fapi.mdx to link to #configure-your-domain instead of #dns-records. Tabs are stateful via localStorage, so deep-linking inside a hidden tab is unreliable; landing one level up at the H2 is robust regardless of which tab the reader had selected previously.

A couple of these changes are bold moves! I'm not married to any of them, but I do think it reads better. Let me know what y'all think @Railly and @alexisintech.

[alexisintech]

wait, are we sure about this: "Production *.vercel.app instances have the hosted Account Portal disabled by default."

if that's true, that is a huge issue and many apps will break if users don't have the components set up in their app correctly. for example, the signin component requires the correct routing to be wired up in order for the flows to work - for most sdk's, that means hosting the component on a splat route and setting certain env vars. which this guide doesn't point to them to or cover.

@Railly tagging you since you added this

[alexisintech]

I could be wrong, maybe they are working perfectly fine if you just drop in the <SignIn /> component on a page with no extra configuration? maybe team sdk considered this. I just want to make sure this is correct @Railly
I'm gonna make a vercel production app to test on as well, but wanted your input!

[alexisintech]

dashboard wont even let me use a vercel.app domain - am I missing something?

[alexisintech]

I've posted a temporary docs review cleaning up copy and organization to make the doc clearer. I had a really hard time understanding it at first read and had to go back through the commits to understand what was trying to be conveyed.
I'm trying to set up a *.vercel.app production app so that I can test, so this PR is waiting on that part.

The updates included:

## OAuth credentials section: bolded the difference between shared and custom credentials. This also uses nomenclature to match the Clerk Dashboard.

## Custom OAuth credentials section: removed it and consolidated it into the OAuth Credentials section, as these sections were duplicated.

### DNS records section:

• Changed the wording for the Vercel tab's introductory paragraph to be consistent with the other tab's introductory paragraph.
• Wrapped the proxy.ts example in a <If sdk="nextjs">. The text reading "If you're using a Next.js proxy" wasn't exactly correct, because all Clerk + Next.js apps use a proxy. It's required, to set up clerkMiddleware(). I updated the text here to be more clear and reorganized the text's order of information so that it follow the user's order of operations.

### Authentication on the app domain section:

• Updated the "on the app domain." text to match the other bullet point's text "on the page where you placed it." for consistency.
• Updated the comments in the examples to be more clear
• #### Standalone redirect helpers section:
  • Updated the copy to be more clear on the use case and necessity of this step.
  • Removed mention of setting up the waitlist, because that is outlined in the waitlist docs and is not a special case for *.vercel.app production apps.
  • Added examples for setting the signInUrl on different SDK's Clerk integrations.

[Railly]

@alexisintech you'll need to be flagged in the new FF. I can set it up for you, just send me your org_id via DM

[alexisintech]

okay so just tested and immediately, I'm noticing a big issue.
so first off, let me explain how I test. I test every new feature using the next.js app router quickstart because it gets me a fresh, out of the box next.js + clerk app. this is helpful, because if a feature requires ANY MORE setup than the basic quickstart, that's how I find when something needs to documented. so I start with the quickstart and clone its companion repo: https://github.com/clerk/clerk-nextjs-app-quickstart
then for this feature, I just deployed it to vercel, and followed the instructions we have written here in the Clerk deploy to production guide.
I go to my app and click "Sign in" and immediately get hit with the error, because of course, it uses Account Portal.
** this is a big issue, because if a user follows the quickstart, which uses the Account Portal (the <SignInButton> and <SignUpButton>), and they don't get anymore fine-grained than that, and then they try to set up a production vercel.app, their app is broken. any users that were relying on the account portal before because they didn't want to do extra configuration, or whatever their reasoning was, are going to have broken apps :'(
trying to self-host the prebuilt components that require routing by throwing them onto a page also won't work, because to get the prebuilt components to not use the account portal, they require extra configuration. in the case of nextjs, they require splat routes. and some even require certain environment variables to be set.
so overall, account portal not working for production vercel.app apps is actually going to require a lot more document updates; we have to show users how to fully move away from the account portal.

if account portal not working for vercel.app production apps is set in stone, then I can try getting something together for this. if it's something that we can possibly get working, that'd save a lot of user error. let me know and i'm here to help!

[manovotny]

Update: I chatted with @Railly and we're going to pause this — the "do not merge" label has been applied.

The docs are between two states right now.

Today, if Account Portal is not available for production *.vercel.app apps, we need to document the app-hosted routes/explicit URL props because otherwise some built-in flows can still point at Account Portal.

But @brkalow's proxied Account Portal work should be the cleaner path here. Once that is landed, it should remove most of the need for those explicit props in the happy path, since Account Portal routes can live behind the app proxy instead.

Given that, we're holding this PR until the proxied Account Portal work lands, or at least until we have the final route/contract. Otherwise we may be documenting a workaround-heavy interim state that should disappear from the happy path.

[github-actions]

⚠️ This PR cannot be merged here. The Clerk docs now live in clerk/clerk under clerk-docs/. Please migrate this PR by running:

pnpm migrate:clerk

Run it locally from the root of this branch and it'll migrate the branch and PR over to clerk/clerk and close this PR automatically. If new commits land on this PR after migration, re-running the same command is safe: it updates the existing clerk/clerk branch and PR instead of creating a new one.

The required Block merges (migration to clerk/clerk required) check on this PR will keep failing on purpose until the PR is migrated and closed.

[manovotny]

This branch and PR were migrated to clerk/clerk. Migration branches/PRs created from this PR (most recent last):

• railly/aie-933-vercel-app-production-docs-docs-migration → https://github.com/clerk/clerk/pull/3033