fix(shared,astro,vue): Allow isSatellite in HeadlessBrowserClerk load() options

[manovotny]

Description

HeadlessBrowserClerk.load() is typed as Without<ClerkOptions, 'isSatellite'>, but the exclusion doesn't match runtime behavior or our own usage:

• The clerk-js implementation is load(options?: ClerkOptions) (packages/clerk-js/src/core/clerk.ts), and the isSatellite getter reads it from those load options.
• IsomorphicClerk passes isSatellite through load() itself — clerk.load(this.options) where IsomorphicClerkOptions includes isSatellite via MultiDomainAndOrProxy (packages/react/src/isomorphicClerk.ts). It only compiles because structural typing lets the extra property through.
• The Clerk constructor only accepts DomainOrProxyUrl, so for standalone @clerk/clerk-js and <script> usage, load() is the only way to set isSatellite — which is exactly what the satellite domains guide instructs.
• The generated API reference currently contradicts itself: the load() signature shows the exclusion while the ClerkOptions table on the same page lists isSatellite.

The Without/re-add pattern is correct on IsomorphicClerkOptions (excluded so MultiDomainAndOrProxy can re-add it with the domain/proxyUrl coupling) and is untouched. This PR only widens load() to match the implementation, in @clerk/shared and the two "Copied from @clerk/react" copies in @clerk/astro and @clerk/vue.

Complements #8845, which updates the isSatellite JSDoc description — this PR fixes the type so the description and the signature agree.

Surfaced while reviewing clerk/clerk-docs#3327.

Checklist

• pnpm test runs as expected. (not run locally — type-only change; relying on CI)
• pnpm build runs as expected. (@clerk/shared and @clerk/astro build clean; @clerk/vue build fails identically on clean main in my environment — node 22 vs required ≥24.15)
• (If applicable) JSDoc comments have been added or updated for any package exports (JSDoc description handled in docs(repo): Update description of isSatellite prop for satellite domains guide #8845)
• (If applicable) Documentation has been updated (flows automatically via the Typedoc pipeline on release)

Type of change

• 🐛 Bug fix

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • HeadlessBrowserClerk.load() now accepts the full set of runtime options (including isSatellite) across Astro, Vue, and shared packages, aligning types with actual behavior.

• Documentation

  • Release notes updated to reflect the corrected API parameter behavior.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 13, 2026 1:50am
swingset	Ready	Preview, Comment	Jun 13, 2026 1:50am

[changeset-bot]

🦋 Changeset detected

Latest commit: 473963d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/vue	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 0a7ec89b-6a61-41ff-8cbf-cebb890f63c9

📥 Commits

Reviewing files that changed from the base of the PR and between 28b0439 and 473963d.

📒 Files selected for processing (1)

• packages/shared/src/types/clerk.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/shared/src/types/clerk.ts

---

📝 Walkthrough

Walkthrough

The PR aligns the HeadlessBrowserClerk.load() type signature across the codebase to accept full ClerkOptions, including isSatellite. Previously, the types explicitly excluded isSatellite despite the runtime supporting it. This change corrects that discrepancy in the shared types, Astro, and Vue packages.

Changes

HeadlessBrowserClerk.load type alignment

Layer / File(s)	Summary
HeadlessBrowserClerk.load type signature update packages/shared/src/types/clerk.ts, packages/astro/src/types.ts, packages/vue/src/types.ts	HeadlessBrowserClerk.load() method's opts parameter is broadened from Without<ClerkOptions, 'isSatellite'> to ClerkOptions across all three type declarations, permitting the isSatellite option.
Release notes .changeset/headless-load-issatellite-type.md	Changeset entry documents the type alignment, clarifying that load() now properly accepts full ClerkOptions matching the runtime behavior.

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested labels: clerk-js

Suggested reviewers:

• wobsoriano

🐰 I hopped through types with care and rhyme,
Found a missing satellite in time,
The runtime smiled, the types agree —
Now load() takes the option free,
A tiny fix, a tidy climb.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: allowing the isSatellite option in HeadlessBrowserClerk.load() across the three affected packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8846

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8846

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8846

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8846

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8846

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8846

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8846

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8846

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8846

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8846

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8846

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8846

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8846

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8846

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8846

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8846

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8846

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8846

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8846

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8846

commit: 473963d

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-13T01:51:39.338Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	1
🟢 Additions	0

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/shared

Current version: 4.17.1
Recommended bump: MINOR → 4.18.0

Subpath ./types

🟡 Non-breaking Changes (1)

Modified: HeadlessBrowserClerk.load

- load: (opts?: Without<ClerkOptions, 'isSatellite'>) => Promise<void>;
+ load: (opts?: ClerkOptions) => Promise<void>;

Static analyzer: Breaking change in property HeadlessBrowserClerk.load: Type changed: (opts?:import("@clerk/shared").Without<import("@clerk/shared").ClerkOptions,'isSatellite'>)=>!Promise:interface<void> → (opts?:import("@clerk/shared").ClerkOptions)=>!Promise:interface<void>

🤖 AI review (reclassified as non-breaking) (95%): The parameter type was widened from Without<ClerkOptions, 'isSatellite'> (ClerkOptions minus the isSatellite property) to the full ClerkOptions. This is an input position change that loosens the constraint, so callers passing the old narrower type still satisfy the new wider type — no existing well-typed call site breaks.

---

Report generated by Break Check

_{Last ran on 473963d.}

[wobsoriano]

👍🏼 👍🏼 👍🏼

[manovotny]

@SarahSoutoul @wobsoriano I don't appear to have merge permissions here, so if one of you do, I'd appreciate an assist. 🙏