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	Jun 3, 2026 3:07am

[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.

[alexisintech]

@manovotny let me know how you feel about these changes, I don't want to hijack anything here! and if it's all good, then this PR should be good to merge 😸💖

[manovotny]

Pushed some polish in 6938c11.

• Switched the email/feature table to <CompareYes /> / <CompareNo /> markers with symmetric *.vercel.app domain / Custom domain columns — custom domain is now visibly the superset. Added a "Branded email domain" row to make the accounts.dev constraint a comparable feature.
• Dropped the ### Considerations heading and integrated the accounts.dev fact into a single cause/effect sentence that introduces the table. The remaining bullets are now just the two action-item setup requirements (prod keys, SDK version).
• Tightened the DNS records cross-link: "skip this section" instead of "step", and the link text matches the heading exactly.
• "After you update your proxy" → "After you update your proxy's matcher" — names exactly what the previous step walked through.
• Restored the "For most production apps, Clerk recommends using a custom domain that you own" hint in vercel.mdx that got dropped during the refactor.

Approving the PR after this, but let me know if any of these changes don't feel right to you.

[alexisintech]

@manovotny yes this is the exact reason I asked about the compareyes and compareno components! 😆 thanks for implementing that, it's beautiful 🙏 feel free to merge

[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