Update Docs for SDK Satellite Domain API and Script Tag Usage

[SarahSoutoul]

🔎 Previews:

• https://clerk.com/docs/pr/ss-docs-11525/guides/dashboard/dns-domains/satellite-domains
• https://clerk.com/docs/pr/ss-docs-11525/js-frontend/getting-started/quickstart

What does this solve? What changed?

A customer integrating satellite domains with ClerkJS was confused because the required configuration is split across two places:

• domain only works when set during initialization
• isSatellite is configured during load()

That split was not obvious in the docs, especially for script-tag users, and it led to trial-and-error around where each option belongs. The docs also did not clearly state that script-tag attributes must be prefixed with data-clerk-*, which made the CDN integration path harder to discover and easier to misconfigure. These updates make the configuration model explicit and add examples for the non-Next.js cases that were missing.

In addition to solving this issue, I also restructured a lot of the page to make it look for UI friendly and easier to read, using <Tabs> and <CodeBlockTabs>. The changes also add/ fix anything that was wrong or confusing when testing this myself.

What changed

• Clarifies that domain must be set during initialization, while isSatellite is set in Clerk.load()
• Documents that script-tag attributes must use the data-clerk-* prefix
• Expands the satellite domains guide beyond Next.js to cover direct @clerk/clerk-js and raw <script> integrations
• Lots of restructure changes.

Deadline

No rush.

Other resources

Linear: https://linear.app/clerk/issue/DOCS-11525/update-docs-for-sdk-satellite-domain-api-and-script-tag-usage

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jun 12, 2026 5:16pm

[SarahSoutoul]

@alexisintech @manovotny okay think I've addressed all comments and feedback on this! Let me know thoughts

[alexisintech]

I've posted my docs review:

• In the warning callout at the top of the doc, re-ordered the information to keep the flow of information sequential
• Updated the heading for the "Using satelliteAutoSync: false (default) with sign-in/sign-up links" section to "Build sign-in and sign-up links" to be more clear on the action the user is taking
  • Moved the callout above the example to keep the order of information sequential
  • Replaced <Tabs> with <If> to be more SDK-specific
• Removed the callout about development vs. production keys in favor of comments in the code example itself to remove visual noise, keep the information close to the source, and so that the user doesn't miss a very important piece of information
• Replaced <Tabs> with <If> to be more SDK-specific.

I think this is fantastic work for the scope of this PR - very nice job Sarah!!
Once this is shipped, there should be a follow-up PR to add more SDK-specificity. Right now, it's very specific to Next.js which is a problem in some areas for users that are using other SDK's:

• There's a middleware section that is Next.js specific
• The examples rely on ClerkProvider, and some SDK's have different integrations

We can tag team the follow up work if that interests you, we can pair on it :) There is an example in the demo repo of how to do satellite apps for React SDK apps: https://github.com/clerk/clerk-multidomain-demo
And we can utilize <If> to make it more specific for apps that aren't using ClerkProvider
I think we can get this guide more SDK-specific all around! I've created a ticket here: https://linear.app/clerk/issue/DOCS-11843/make-the-satellite-domains-guide-more-sdk-specific

Nice work on this Sarah 😸💖

[alexisintech]

another question!

do we want to keep pages router support in this? we haven't been adding pages router examples to our guides, and imo, I think we can remove it! the examples are not much different.

[SarahSoutoul]

another question!

do we want to keep pages router support in this? we haven't been adding pages router examples to our guides, and imo, I think we can remove it! the examples are not much different.

Yeah that's a fair statement! Let me remove them.

In terms of the rest, thanks for creating a ticket - happy to work on this with you and pair. Def think we could make this guide even better by making it SDK-specific, but as you said, not the scope of this PR/ ticket.

[SarahSoutoul]

Okay @alexisintech - have done the following:

• Removed pages router: Remove pages router
• Removed an unnecessary line that didn't make sense after switching to : Remove unnecessary line
• Created a JS PR to update the description of isSatellite prop, whcih was part of the Linear ticket. That description change was included in this PR initially but with the /object/ reference docs changes, the partial containing the prop got removed and is now coming from Typedoc.

I'll look at the ticket you created next and come up with a proposal, and we can jump on a call sometime next week to discuss.

[manovotny]

Pushed some changes directly in 112443b.

• Reworded the data-clerk-* callout — the script tag reads exactly three attributes (data-clerk-publishable-key, data-clerk-proxy-url, data-clerk-domain, verified in clerk-js/src/index.browser.ts), so the callout now names them instead of saying "any Clerk option," and points everything else at load().
• Added a sentence to the npm-module intro noting the examples build on the JavaScript Quickstart setup — without the quickstart's @clerk/ui loader, window.__internal_ClerkUICtor is undefined and the prebuilt components silently won't mount.
• Simplified clerkMiddleware(async (auth, req) => {}, options) to clerkMiddleware(options) — it's a documented overload, and the empty callback left unused params behind after the force-auth removal.

[manovotny]

Heads up: the regenerated reference this guide links to shows load() typed as Without<ClerkOptions, 'isSatellite'> — while the ClerkOptions table on the same page lists isSatellite.

The guide is right at runtime: clerk-js's load() accepts full ClerkOptions, the isSatellite getter reads it from there, and the constructor only takes domain/proxyUrl, so load() is the only path for plain JS.

clerk/javascript#8845 fixes the description and clerk/javascript#8846 fixes the type — once those release, the Typedoc sync resolves the contradiction. Nothing to change in this PR.