feat(docs): document satelliteAutoSync option for satellite domains#2998
Merged
nikosdouvlis merged 6 commits intocore-3from Feb 2, 2026
Merged
feat(docs): document satelliteAutoSync option for satellite domains#2998nikosdouvlis merged 6 commits intocore-3from
nikosdouvlis merged 6 commits intocore-3from
Conversation
Why: Core 3 changes satellite domain behavior to skip automatic handshake redirects by default, improving performance for apps with anonymous visitors. Users need guidance on the new behavior and migration path. What changed: - Added "How authentication syncing works" section explaining both modes - Documented satelliteAutoSync prop in ClerkProvider, clerkMiddleware, and backend options - Added Core 2 migration section with comparison table and opt-in instructions - Updated verification steps to reflect the new default (no auto-redirect)
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
manovotny
reviewed
Jan 23, 2026
Contributor
manovotny
left a comment
There was a problem hiding this comment.
Nice changes! A few questions and some suggestions. Let me know if you agree or disagree with any of them.
| 1. Completing sign-in on the primary domain. You will be automatically redirected back to the satellite domain with an active session. | ||
| 1. If you were already signed in on the primary domain, the redirect back happens immediately with no additional user action. | ||
|
|
||
| After the initial sync, signing out from either domain will sign you out from all connected domains. |
Contributor
There was a problem hiding this comment.
The text here is nearly identical to the text on lines 39-42. Do we need it in both places?
Contributor
There was a problem hiding this comment.
Think it's fine to keep it, but I would make it an actual step.
SarahSoutoul
requested changes
Jan 26, 2026
| 1. Completing sign-in on the primary domain. You will be automatically redirected back to the satellite domain with an active session. | ||
| 1. If you were already signed in on the primary domain, the redirect back happens immediately with no additional user action. | ||
|
|
||
| After the initial sync, signing out from either domain will sign you out from all connected domains. |
Contributor
There was a problem hiding this comment.
Think it's fine to keep it, but I would make it an actual step.
Why: PR #2998 review identified several issues: wording inconsistencies, duplicate content, callout stacking, and style guide violations. What changed: - Change "click" to "select" per docs style guide - Move CAUTION callout under "How authentication syncing works" to avoid stacking - Remove duplicate verification steps, reference earlier section instead - Remove redundant "Recommended approach" section - Mark satelliteAutoSync as optional with ? in ClerkProvider properties - Expand clerk-options.mdx description for consistency with other partials - Revert filename from middleware.ts to proxy.ts - Soften code comment about performance cost - Change "legacy behavior" to "original Core 2 behavior"
…tial Why: Reviewer confirmed partials within partials work, so we can DRY up the satelliteAutoSync description that was duplicated across three files. What changed: - Create _partials/satellite-auto-sync-description.mdx with shared text - Update clerk-provider/properties.mdx, clerk-middleware-options.mdx, and clerk-options.mdx to use the shared partial
Why: The list of frameworks with full SSR support for multi-domain was outdated. Added TanStack Start and Nuxt, removed Remix.
SarahSoutoul
approved these changes
Jan 29, 2026
Contributor
|
LGTM @nikosdouvlis! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Core 3 changes satellite domain behavior — satellite apps no longer automatically redirect to the primary domain on first visit to sync auth state. This eliminates unnecessary latency for apps where most visitors are anonymous. Users need documentation on the new
satelliteAutoSyncoption and a migration path from Core 2.What changed
satelliteAutoSyncprop in ClerkProvider, clerkMiddleware, and backend options