feat(docs): document satelliteAutoSync option for satellite domains (#2998)

Co-authored-by: Sarah Soutoul <sarah@clerk.dev>

Author: nikosdouvlis

docs/_partials/clerk-middleware-options.mdx

@@ -36,6 +36,13 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
 
   ---
 
+  - `satelliteAutoSync?`
+  - `boolean`
+
+  <Include src="_partials/satellite-auto-sync-description" />
+
+  ---
+
   - `jwtKey`
   - `string`
 

docs/_partials/clerk-options.mdx

@@ -34,6 +34,13 @@
 
   ---
 
+  - `satelliteAutoSync?`
+  - `boolean`
+
+  <Include src="_partials/satellite-auto-sync-description" />
+
+  ---
+
   - `proxyUrl?`
   - `string`
 

docs/_partials/clerk-provider/properties.mdx

@@ -85,6 +85,13 @@
 
   ---
 
+  - `satelliteAutoSync?`
+  - `boolean`
+
+  <Include src="_partials/satellite-auto-sync-description" />
+
+  ---
+
   - `localization`
   - <code>[Localization](/docs/guides/customizing-clerk/localization) | undefined</code>
 

docs/_partials/satellite-auto-sync-description.mdx

@@ -0,0 +1 @@
+Controls whether a satellite app automatically syncs authentication state with the primary domain on first page load. When `false` (default), the satellite app skips the automatic redirect if no session cookies exist, and only triggers the handshake after the user initiates a sign-in or sign-up action. When `true`, the satellite app redirects to the primary domain on every first visit to sync state. Defaults to `false`. See [satellite domains](/docs/guides/dashboard/dns-domains/satellite-domains) for more details.

docs/guides/dashboard/dns-domains/satellite-domains.mdx

@@ -27,7 +27,21 @@ Your "primary" domain is where the authentication state lives, and satellite dom
 
 Users must complete both the sign-in and sign-up flows on the primary domain by using the [`<SignIn />`](/docs/reference/components/authentication/sign-in) component or [`useSignIn()`](/docs/reference/hooks/use-sign-in) hook for sign-in and [`<SignUp />`](/docs/reference/components/authentication/sign-up) component or [`useSignUp()`](/docs/reference/hooks/use-sign-up) hook for sign-up.
 
-To access authentication state from a satellite domain, users will be transparently redirected to the primary domain. If users need to sign in, they must be redirected to a sign in flow hosted on the primary domain, then redirected back to the originating satellite domain. The same redirection process applies to sign-up flows.
+### How authentication syncing works
+
+> [!CAUTION]
+> If you are upgrading from Core 2, see the [migration section](#migrating-from-core-2) for behavior changes that may affect your satellite applications.
+
+The syncing behavior between satellite and primary domains is controlled by the `satelliteAutoSync` option.
+
+With `satelliteAutoSync: false` (the default), satellite domains do not automatically sync authentication state with the primary domain when a user visits the page. This means there is no upfront performance cost for users visiting a satellite domain. Authentication state is only synced when a user initiates a sign-in or sign-up action:
+
+1. When a user selects "Sign in" on the satellite domain, they are redirected to the primary domain.
+1. If the user is already signed in on the primary domain, they are immediately redirected back to the satellite domain with the existing auth state — no additional user action is required.
+1. If the user is not signed in on the primary domain, they complete the sign-in (or sign-up) flow there and are then redirected back to the satellite domain.
+1. After the initial sync, signing out from either domain signs out from all domains.
+
+If you set `satelliteAutoSync: true`, the satellite domain will automatically redirect to the primary domain on first load to sync authentication state, even if the user has no session. This matches the original Core 2 behavior and is useful if you want users who are already signed in on the primary domain to be automatically recognized on the satellite without needing to select "Sign in". However, this comes with a performance cost since every first visit triggers a redirect.
 
 ## How to add satellite domains
 
@@ -37,7 +51,7 @@ To access authentication state from a satellite domain, users will be transparen
   ### Create your application and install Clerk
 
   > [!WARNING]
-  > Currently, multi-domain can be added to any Next.js or Remix application. For other React frameworks, multi-domain is still supported as long as you do not use server rendering or hydration.
+  > Currently, multi-domain can be added to any Next.js, TanStack Start, or Nuxt application. For other React frameworks, multi-domain is still supported as long as you do not use server rendering or hydration.
 
   To get started, you need to create an application from the [Clerk Dashboard](https://dashboard.clerk.com/). Once you create an instance via the Clerk Dashboard, you will be prompted to choose a domain. This is your primary domain. For the purposes of this guide:
 
@@ -331,6 +345,10 @@ To access authentication state from a satellite domain, users will be transparen
             domain: 'https://satellite.dev',
             // Or, in development:
             // domain: 'http://localhost:3001',
+
+            // Uncomment to automatically sync auth state on first load.
+            // This will add a redirect on first visit, which comes with a performance cost since every first visit triggers a redirect.
+            // satelliteAutoSync: true,
           }
 
           export default clerkMiddleware(async (auth, req) => {
@@ -421,17 +439,43 @@ To access authentication state from a satellite domain, users will be transparen
     </Tab>
   </Tabs>
 
-  ### Ready to go 🎉
+  ### Ready to go
 
   Your satellite application should now be able to access the authentication state from your satellite domain!
 
-  You can see it in action by:
-
-  1. Visiting the primary domain and signing in.
-  1. Visiting the satellite domain.
-  1. You now have an active session in the satellite domain, so you can see the [`<UserProfile />`](/docs/reference/components/user/user-profile) component and update your information.
+  To verify it's working, visit your satellite domain and select "Sign in" — you should be redirected to the primary domain and back with an active session. For details on the sync flow, see the [How authentication syncing works](#how-authentication-syncing-works) section.
 
   You can repeat this process and create as many satellite applications as you need.
 </Steps>
 
+## Migrating from Core 2
+
+In Core 2, satellite applications automatically synced authentication state with the primary domain on every first page load by redirecting users to the primary domain and back. This happened regardless of whether the user had an active session, which caused unnecessary latency for apps where most visitors are anonymous.
+
+In Core 3, this behavior is controlled by the `satelliteAutoSync` option, which defaults to `false`. This means satellite apps no longer perform automatic redirects on first visit.
+
+### What changed
+
+| | Core 2 | Core 3 (default) |
+| - | - | - |
+| First visit to satellite | Redirects to primary domain to sync state, then back | No redirect, page loads immediately |
+| Sign-in flow | Same as Core 3 | User selects "Sign in" → redirected to primary → signs in → redirected back |
+| Already signed in on primary | Automatically synced on first visit | Only synced after user selects "Sign in" (redirect is instant, no user action needed) |
+| Sign-out | Signs out from all domains | Signs out from all domains |
+| Performance | Redirect on every first visit | No upfront cost |
+
+### To preserve Core 2 behavior
+
+If your application relies on users being automatically recognized on the satellite domain without selecting "Sign in", set `satelliteAutoSync` to `true`:
+
+```ts {{ prettier: false }}
+// In your middleware options or ClerkProvider props
+{
+  isSatellite: true,
+  domain: 'satellite.dev',
+  signInUrl: 'https://primary.dev/sign-in',
+  satelliteAutoSync: true, // Opt-in to automatic sync on first load
+}
+```
+
 If you have any questions about satellite domains, or you're having any trouble setting this up, contact [support@clerk.com](mailto:support@clerk.com)