feat(*): optimize satellite handshakes and introduce satelliteAutoSync prop

Satellite domains previously always triggered a handshake redirect to the primary
domain on first visit, even when users weren't authenticated. This caused unnecessary
latency and poor UX for apps where most visitors are anonymous.

Changes:
- Add `satelliteAutoSync` option (defaults to false)
- When false, satellites skip handshake if no cookies exist and no sync trigger
- Use `__clerk_synced` query param: 'false' triggers sync, 'true' marks completion
- Server-side redirects include sync param for post-sign-in handshake trigger
- Client-side adds sync param to forceRedirectUrl and fallbackRedirectUrl
- TanStack Start middleware supports callback function for dynamic options

Packages affected:
- @clerk/backend: authenticateRequest logic and redirect handling
- @clerk/clerk-js: CSR support and redirect URL modification
- @clerk/shared: sync constants and option types
- @clerk/nextjs, @clerk/astro, @clerk/tanstack-react-start: option passthrough

Author: nikosdouvlis

.changeset/satellite-auto-sync.md

@@ -0,0 +1,128 @@
+---
+"@clerk/backend": minor
+"@clerk/shared": minor
+"@clerk/clerk-js": minor
+"@clerk/tanstack-react-start": minor
+"@clerk/nextjs": patch
+"@clerk/astro": patch
+---
+
+Add `satelliteAutoSync` option to optimize satellite app handshake behavior
+
+Satellite apps currently trigger a handshake redirect on every first page load, even when no cookies exist. This creates unnecessary redirects to the primary domain for apps where most users aren't authenticated.
+
+**New option: `satelliteAutoSync`** (default: `false`)
+- When `false` (default): Skip automatic handshake if no session cookies exist, only trigger after explicit sign-in action
+- When `true`: Satellite apps automatically trigger handshake on first load (previous behavior)
+
+**New query parameter: `__clerk_sync`**
+- `__clerk_sync=1` (NeedsSync): Triggers handshake after returning from primary sign-in
+- `__clerk_sync=2` (Completed): Prevents re-sync loop after handshake completes
+
+Backwards compatible: Still reads legacy `__clerk_synced=true` parameter.
+
+**SSR redirect fix**: Server-side redirects (e.g., `redirectToSignIn()` from middleware) now correctly add `__clerk_sync=1` to the return URL for satellite apps. This ensures the handshake is triggered when the user returns from sign-in on the primary domain.
+
+**CSR redirect fix**: Client-side redirects now add `__clerk_sync=1` to all redirect URL variants (`forceRedirectUrl`, `fallbackRedirectUrl`) for satellite apps, not just the default `redirectUrl`.
+
+## Usage
+
+### SSR (Next.js Middleware)
+```typescript
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware({
+  isSatellite: true,
+  domain: 'satellite.example.com',
+  signInUrl: 'https://primary.example.com/sign-in',
+  // Set to true to automatically sync auth state on first load
+  satelliteAutoSync: true,
+});
+```
+
+### SSR (TanStack Start)
+```typescript
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
+
+export default clerkMiddleware({
+  isSatellite: true,
+  domain: 'satellite.example.com',
+  signInUrl: 'https://primary.example.com/sign-in',
+  // Set to true to automatically sync auth state on first load
+  satelliteAutoSync: true,
+});
+```
+
+### CSR (ClerkProvider)
+```tsx
+<ClerkProvider
+  publishableKey="pk_..."
+  isSatellite={true}
+  domain="satellite.example.com"
+  signInUrl="https://primary.example.com/sign-in"
+  // Set to true to automatically sync auth state on first load
+  satelliteAutoSync={true}
+>
+  {children}
+</ClerkProvider>
+```
+
+### SSR (TanStack Start with callback)
+```typescript
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
+
+// Options callback - receives context object, returns options
+export default clerkMiddleware(({ url }) => ({
+  isSatellite: true,
+  domain: 'satellite.example.com',
+  signInUrl: 'https://primary.example.com/sign-in',
+  satelliteAutoSync: url.pathname.startsWith('/dashboard'),
+}));
+```
+
+## Migration Guide
+
+### Behavior change: `satelliteAutoSync` defaults to `false`
+
+Previously, satellite apps would automatically trigger a handshake redirect on every first page load to sync authentication state with the primary domain—even when no session cookies existed. This caused unnecessary redirects to the primary domain for users who weren't authenticated.
+
+The new default (`satelliteAutoSync: false`) provides a better experience for end users. Performance-wise, the satellite app can be shown immediately without attempting to sync state first, which is the right behavior for most use cases.
+
+**To preserve the previous behavior** where visiting a satellite while already signed in on the primary domain automatically syncs your session, set `satelliteAutoSync: true`:
+
+```typescript
+export default clerkMiddleware({
+  isSatellite: true,
+  domain: 'satellite.example.com',
+  signInUrl: 'https://primary.example.com/sign-in',
+  satelliteAutoSync: true, // Opt-in to automatic sync on first load
+});
+```
+
+### TanStack Start: Function props to options callback
+
+The `clerkMiddleware` function no longer accepts individual props as functions. If you were using the function form for props like `domain`, `proxyUrl`, or `isSatellite`, migrate to the options callback pattern.
+
+**Before (prop function form - no longer supported):**
+```typescript
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
+
+export default clerkMiddleware({
+  isSatellite: true,
+  // ❌ Function form for individual props no longer works
+  domain: (url) => url.hostname,
+});
+```
+
+**After (options callback form):**
+```typescript
+import { clerkMiddleware } from '@clerk/tanstack-react-start/server';
+
+// ✅ Wrap entire options in a callback function
+export default clerkMiddleware(({ url }) => ({
+  isSatellite: true,
+  domain: url.hostname,
+}));
+```
+
+The callback receives a context object with the `url` property (a `URL` instance) and can return options synchronously or as a Promise for async configuration.

integration/tests/handshake.test.ts

@@ -42,13 +42,15 @@ test.describe('Client handshake @generic', () => {
         () => `import { clerkMiddleware } from '@clerk/nextjs/server';
 
     export const middleware = (req, evt) => {
+      const satelliteAutoSyncHeader = req.headers.get('x-satellite-auto-sync');
       return clerkMiddleware({
         publishableKey: req.headers.get("x-publishable-key"),
         secretKey: req.headers.get("x-secret-key"),
         proxyUrl: req.headers.get("x-proxy-url"),
         domain: req.headers.get("x-domain"),
         isSatellite: req.headers.get('x-satellite') === 'true',
         signInUrl: req.headers.get("x-sign-in-url"),
+        satelliteAutoSync: satelliteAutoSyncHeader === null ? undefined : satelliteAutoSyncHeader === 'true',
       })(req, evt)
     };
 
@@ -567,6 +569,86 @@ test.describe('Client handshake @generic', () => {
     expect(res.status).toBe(200);
   });
 
+  test('signed out satellite with satelliteAutoSync=false skips handshake - prod', async () => {
+    const config = generateConfig({
+      mode: 'live',
+    });
+    const res = await fetch(app.serverUrl + '/', {
+      headers: new Headers({
+        'X-Publishable-Key': config.pk,
+        'X-Secret-Key': config.sk,
+        'X-Satellite': 'true',
+        'X-Domain': 'example.com',
+        'X-Satellite-Auto-Sync': 'false',
+        'Sec-Fetch-Dest': 'document',
+      }),
+      redirect: 'manual',
+    });
+    // Should NOT redirect to handshake when satelliteAutoSync=false and no cookies
+    expect(res.status).toBe(200);
+  });
+
+  test('signed out satellite with satelliteAutoSync=false triggers handshake when __clerk_synced=false - prod', async () => {
+    const config = generateConfig({
+      mode: 'live',
+    });
+    const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+      headers: new Headers({
+        'X-Publishable-Key': config.pk,
+        'X-Secret-Key': config.sk,
+        'X-Satellite': 'true',
+        'X-Domain': 'example.com',
+        'X-Satellite-Auto-Sync': 'false',
+        'Sec-Fetch-Dest': 'document',
+      }),
+      redirect: 'manual',
+    });
+    // Should redirect to handshake when __clerk_synced=false is present
+    expect(res.status).toBe(307);
+    const locationUrl = new URL(res.headers.get('location'));
+    expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+    expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+  });
+
+  test('signed out satellite skips handshake when __clerk_synced=true (completed) - prod', async () => {
+    const config = generateConfig({
+      mode: 'live',
+    });
+    const res = await fetch(app.serverUrl + '/?__clerk_synced=true', {
+      headers: new Headers({
+        'X-Publishable-Key': config.pk,
+        'X-Secret-Key': config.sk,
+        'X-Satellite': 'true',
+        'X-Domain': 'example.com',
+        'Sec-Fetch-Dest': 'document',
+      }),
+      redirect: 'manual',
+    });
+    // Should NOT redirect when __clerk_synced=true indicates sync already completed
+    expect(res.status).toBe(200);
+  });
+
+  test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+    const config = generateConfig({
+      mode: 'live',
+    });
+    const res = await fetch(app.serverUrl + '/', {
+      headers: new Headers({
+        'X-Publishable-Key': config.pk,
+        'X-Secret-Key': config.sk,
+        'X-Satellite': 'true',
+        'X-Domain': 'example.com',
+        'X-Satellite-Auto-Sync': 'true',
+        'Sec-Fetch-Dest': 'document',
+      }),
+      redirect: 'manual',
+    });
+    // Should redirect to handshake with default/true satelliteAutoSync
+    expect(res.status).toBe(307);
+    const locationUrl = new URL(res.headers.get('location'));
+    expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+  });
+
   test('missing session token, missing uat (indicating signed out), missing devbrowser - dev', async () => {
     const config = generateConfig({
       mode: 'test',

packages/astro/src/server/clerk-middleware.ts

@@ -300,6 +300,7 @@ function decorateAstroLocal(
           signInUrl: requestState.signInUrl,
           signUpUrl: requestState.signUpUrl,
           sessionStatus: requestState.toAuth()?.sessionStatus,
+          isSatellite: requestState.isSatellite,
         }).redirectToSignIn({
           returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl.toString(),
         });
@@ -422,6 +423,7 @@ const handleControlFlowErrors = (
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         publishableKey: getSafeEnv(context).pk!,
         sessionStatus: requestState.toAuth()?.sessionStatus,
+        isSatellite: requestState.isSatellite,
       }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
     default:
       throw e;

packages/backend/src/__tests__/createRedirect.test.ts

@@ -99,26 +99,44 @@ describe('redirect(redirectAdapter)', () => {
       );
     });
 
-    it('removes __clerk_synced when cross-origin redirect', () => {
-      const returnBackUrl = 'https://current.url:3000/path?__clerk_synced=true&q=1#hash';
-      const encodedUrl = 'https%3A%2F%2Fcurrent.url%3A3000%2Fpath%3Fq%3D1%23hash';
-      const signUpUrl = 'https://lcl.dev/sign-up';
+    it('adds __clerk_synced=false to returnBackUrl for satellite apps on cross-origin redirect', () => {
+      const returnBackUrl = 'https://satellite.example.com/dashboard';
+      const encodedUrl = 'https%3A%2F%2Fsatellite.example.com%2Fdashboard%3F__clerk_synced%3Dfalse';
+      const signInUrl = 'https://primary.example.com/sign-in';
 
       const redirectAdapterSpy = vi.fn().mockImplementation(_url => 'redirectAdapterValue');
-      const { redirectToSignUp } = createRedirect({
-        baseUrl: 'http://www.clerk.com',
-        devBrowserToken: 'deadbeef',
+      const { redirectToSignIn } = createRedirect({
+        baseUrl: 'https://satellite.example.com',
         redirectAdapter: redirectAdapterSpy,
-        publishableKey: 'pk_test_Y2xlcmsubGNsLmRldiQ',
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
         sessionStatus: 'active',
-        signUpUrl,
+        signInUrl,
+        isSatellite: true,
       });
 
-      const result = redirectToSignUp({ returnBackUrl });
+      const result = redirectToSignIn({ returnBackUrl });
       expect(result).toBe('redirectAdapterValue');
-      expect(redirectAdapterSpy).toHaveBeenCalledWith(
-        `${signUpUrl}?redirect_url=${encodedUrl}&__clerk_db_jwt=deadbeef`,
-      );
+      expect(redirectAdapterSpy).toHaveBeenCalledWith(`${signInUrl}?redirect_url=${encodedUrl}`);
+    });
+
+    it('does not add __clerk_synced=false for non-satellite apps', () => {
+      const returnBackUrl = 'https://app.example.com/dashboard';
+      const encodedUrl = 'https%3A%2F%2Fapp.example.com%2Fdashboard';
+      const signInUrl = 'https://accounts.example.com/sign-in';
+
+      const redirectAdapterSpy = vi.fn().mockImplementation(_url => 'redirectAdapterValue');
+      const { redirectToSignIn } = createRedirect({
+        baseUrl: 'https://app.example.com',
+        redirectAdapter: redirectAdapterSpy,
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+        sessionStatus: 'active',
+        signInUrl,
+        isSatellite: false,
+      });
+
+      const result = redirectToSignIn({ returnBackUrl });
+      expect(result).toBe('redirectAdapterValue');
+      expect(redirectAdapterSpy).toHaveBeenCalledWith(`${signInUrl}?redirect_url=${encodedUrl}`);
     });
 
     it('returns path based url with development (kima) publishableKey (with staging Clerk) but without signUpUrl to redirectToSignUp', () => {
@@ -342,25 +360,5 @@ describe('redirect(redirectAdapter)', () => {
         `https://included.katydid-92.accounts.dev/sign-up/tasks?redirect_url=${encodedUrl}&__clerk_db_jwt=deadbeef`,
       );
     });
-
-    it('removes __clerk_synced when cross-origin redirect', () => {
-      const returnBackUrl = 'https://current.url:3000/path?__clerk_synced=true&q=1#hash';
-      const encodedUrl = 'https%3A%2F%2Fcurrent.url%3A3000%2Fpath%3Fq%3D1%23hash';
-
-      const redirectAdapterSpy = vi.fn().mockImplementation(_url => 'redirectAdapterValue');
-      const { redirectToSignUp } = createRedirect({
-        baseUrl: 'http://www.clerk.com',
-        devBrowserToken: 'deadbeef',
-        redirectAdapter: redirectAdapterSpy,
-        publishableKey: 'pk_test_Y2xlcmsubGNsLmRldiQ',
-        sessionStatus: 'pending',
-      });
-
-      const result = redirectToSignUp({ returnBackUrl });
-      expect(result).toBe('redirectAdapterValue');
-      expect(redirectAdapterSpy).toHaveBeenCalledWith(
-        `https://accounts.lcl.dev/sign-up/tasks?redirect_url=${encodedUrl}&__clerk_db_jwt=deadbeef`,
-      );
-    });
   });
 });

packages/backend/src/constants.ts

@@ -74,6 +74,17 @@ const ContentTypes = {
   Json: 'application/json',
 } as const;
 
+/**
+ * Sync status values for the __clerk_synced query parameter.
+ * Used to coordinate satellite domain authentication flows.
+ */
+export const ClerkSyncStatus = {
+  /** Not synced - satellite needs handshake after returning from primary sign-in */
+  NeedsSync: 'false',
+  /** Sync completed - prevents re-sync loop after handshake completes */
+  Completed: 'true',
+} as const;
+
 /**
  * @internal
  */
@@ -83,6 +94,7 @@ export const constants = {
   Headers,
   ContentTypes,
   QueryParameters,
+  ClerkSyncStatus,
 } as const;
 
 export type Constants = typeof constants;