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

nikosdouvlis · 2026-01-14T09:52:51Z

Description

Why:
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.

What changed:

Added satelliteAutoSync option (defaults to true for backward compatibility)
When false, satellites skip handshake if no cookies exist and no sync trigger
Uses __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

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Added satelliteAutoSync option (defaults to true) to control automatic handshake for satellite apps
- Introduced multi-domain sync status values and a query-based sync trigger for cross-domain flows
- Middleware can now accept a configuration callback for dynamic option resolution
Bug Fixes
- Fixed SSR/CSR redirect handling to reliably append sync triggers and avoid redirect loops
Tests
- Expanded tests covering satellite sync, handshake, and redirect behaviors
Documentation
- Release notes and examples updated for satelliteAutoSync and sync flow changes

_{✏️ Tip: You can customize this high-level summary in your review settings.}

changeset-bot · 2026-01-14T09:52:55Z

🦋 Changeset detected

Latest commit: 03df463

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/backend	Minor
@clerk/shared	Minor
@clerk/clerk-js	Minor
@clerk/tanstack-react-start	Minor
@clerk/nextjs	Patch
@clerk/astro	Patch
@clerk/agent-toolkit	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/testing	Patch
@clerk/chrome-extension	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/react	Patch
@clerk/ui	Patch
@clerk/vue	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

vercel · 2026-01-14T09:52:56Z

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 16, 2026 11:27am

pkg-pr-new · 2026-01-14T09:56:10Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7597

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7597

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 03df463

nikosdouvlis · 2026-01-14T09:59:15Z

!snapshot

coderabbitai · 2026-01-14T10:00:02Z

📝 Walkthrough

Walkthrough

Adds a satelliteAutoSync option and multi-domain sync flow using a new __clerk_sync query parameter and two sync-status constants (ClerkSyncStatus / CLERK_SYNCED_STATUS). Backend token handling and redirect logic were updated to read/write sync state and conditionally trigger or skip satellite handshakes. Client clerk.ts now appends sync triggers to redirect URLs. createRedirect and redirect helpers propagate isSatellite and set sync flags for cross‑origin flows. Public types were extended (satelliteAutoSync, ClerkMiddlewareOptionsCallback) and tests were added/adjusted for the new sync behaviors.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective: optimizing satellite handshakes and introducing the satelliteAutoSync feature, which are the core changes reflected throughout all modified files.

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

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

clerk-cookie · 2026-01-14T10:01:20Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114095952
@clerk/astro	3.0.0-snapshot.v20260114095952
@clerk/backend	3.0.0-snapshot.v20260114095952
@clerk/chrome-extension	3.0.0-snapshot.v20260114095952
@clerk/clerk-js	6.0.0-snapshot.v20260114095952
@clerk/dev-cli	1.0.0-snapshot.v20260114095952
@clerk/expo	3.0.0-snapshot.v20260114095952
@clerk/expo-passkeys	1.0.0-snapshot.v20260114095952
@clerk/express	2.0.0-snapshot.v20260114095952
@clerk/fastify	2.6.9-snapshot.v20260114095952
@clerk/localizations	4.0.0-snapshot.v20260114095952
@clerk/msw	0.0.1-snapshot.v20260114095952
@clerk/nextjs	7.0.0-snapshot.v20260114095952
@clerk/nuxt	2.0.0-snapshot.v20260114095952
@clerk/react	6.0.0-snapshot.v20260114095952
@clerk/react-router	3.0.0-snapshot.v20260114095952
@clerk/shared	4.0.0-snapshot.v20260114095952
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114095952
@clerk/testing	2.0.0-snapshot.v20260114095952
@clerk/ui	1.0.0-snapshot.v20260114095952
@clerk/upgrade	2.0.0-snapshot.v20260114095952
@clerk/vue	2.0.0-snapshot.v20260114095952

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

nikosdouvlis · 2026-01-14T11:40:54Z

!snapshot

clerk-cookie · 2026-01-14T11:43:18Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114114137
@clerk/astro	3.0.0-snapshot.v20260114114137
@clerk/backend	3.0.0-snapshot.v20260114114137
@clerk/chrome-extension	3.0.0-snapshot.v20260114114137
@clerk/clerk-js	6.0.0-snapshot.v20260114114137
@clerk/dev-cli	1.0.0-snapshot.v20260114114137
@clerk/expo	3.0.0-snapshot.v20260114114137
@clerk/expo-passkeys	1.0.0-snapshot.v20260114114137
@clerk/express	2.0.0-snapshot.v20260114114137
@clerk/fastify	2.6.9-snapshot.v20260114114137
@clerk/localizations	4.0.0-snapshot.v20260114114137
@clerk/msw	0.0.1-snapshot.v20260114114137
@clerk/nextjs	7.0.0-snapshot.v20260114114137
@clerk/nuxt	2.0.0-snapshot.v20260114114137
@clerk/react	6.0.0-snapshot.v20260114114137
@clerk/react-router	3.0.0-snapshot.v20260114114137
@clerk/shared	4.0.0-snapshot.v20260114114137
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114114137
@clerk/testing	2.0.0-snapshot.v20260114114137
@clerk/ui	1.0.0-snapshot.v20260114114137
@clerk/upgrade	2.0.0-snapshot.v20260114114137
@clerk/vue	2.0.0-snapshot.v20260114114137

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

nikosdouvlis · 2026-01-14T11:46:11Z

!snapshot

clerk-cookie · 2026-01-14T11:48:22Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114114652
@clerk/astro	3.0.0-snapshot.v20260114114652
@clerk/backend	3.0.0-snapshot.v20260114114652
@clerk/chrome-extension	3.0.0-snapshot.v20260114114652
@clerk/clerk-js	6.0.0-snapshot.v20260114114652
@clerk/dev-cli	1.0.0-snapshot.v20260114114652
@clerk/expo	3.0.0-snapshot.v20260114114652
@clerk/expo-passkeys	1.0.0-snapshot.v20260114114652
@clerk/express	2.0.0-snapshot.v20260114114652
@clerk/fastify	2.6.9-snapshot.v20260114114652
@clerk/localizations	4.0.0-snapshot.v20260114114652
@clerk/msw	0.0.1-snapshot.v20260114114652
@clerk/nextjs	7.0.0-snapshot.v20260114114652
@clerk/nuxt	2.0.0-snapshot.v20260114114652
@clerk/react	6.0.0-snapshot.v20260114114652
@clerk/react-router	3.0.0-snapshot.v20260114114652
@clerk/shared	4.0.0-snapshot.v20260114114652
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114114652
@clerk/testing	2.0.0-snapshot.v20260114114652
@clerk/ui	1.0.0-snapshot.v20260114114652
@clerk/upgrade	2.0.0-snapshot.v20260114114652
@clerk/vue	2.0.0-snapshot.v20260114114652

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

nikosdouvlis · 2026-01-14T12:44:17Z

!snapshot

clerk-cookie · 2026-01-14T12:46:18Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114124449
@clerk/astro	3.0.0-snapshot.v20260114124449
@clerk/backend	3.0.0-snapshot.v20260114124449
@clerk/chrome-extension	3.0.0-snapshot.v20260114124449
@clerk/clerk-js	6.0.0-snapshot.v20260114124449
@clerk/dev-cli	1.0.0-snapshot.v20260114124449
@clerk/expo	3.0.0-snapshot.v20260114124449
@clerk/expo-passkeys	1.0.0-snapshot.v20260114124449
@clerk/express	2.0.0-snapshot.v20260114124449
@clerk/fastify	2.6.9-snapshot.v20260114124449
@clerk/localizations	4.0.0-snapshot.v20260114124449
@clerk/msw	0.0.1-snapshot.v20260114124449
@clerk/nextjs	7.0.0-snapshot.v20260114124449
@clerk/nuxt	2.0.0-snapshot.v20260114124449
@clerk/react	6.0.0-snapshot.v20260114124449
@clerk/react-router	3.0.0-snapshot.v20260114124449
@clerk/shared	4.0.0-snapshot.v20260114124449
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114124449
@clerk/testing	2.0.0-snapshot.v20260114124449
@clerk/ui	1.0.0-snapshot.v20260114124449
@clerk/upgrade	2.0.0-snapshot.v20260114124449
@clerk/vue	2.0.0-snapshot.v20260114124449

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

nikosdouvlis · 2026-01-14T13:03:51Z

!snapshot

clerk-cookie · 2026-01-14T13:05:58Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114130428
@clerk/astro	3.0.0-snapshot.v20260114130428
@clerk/backend	3.0.0-snapshot.v20260114130428
@clerk/chrome-extension	3.0.0-snapshot.v20260114130428
@clerk/clerk-js	6.0.0-snapshot.v20260114130428
@clerk/dev-cli	1.0.0-snapshot.v20260114130428
@clerk/expo	3.0.0-snapshot.v20260114130428
@clerk/expo-passkeys	1.0.0-snapshot.v20260114130428
@clerk/express	2.0.0-snapshot.v20260114130428
@clerk/fastify	2.6.9-snapshot.v20260114130428
@clerk/localizations	4.0.0-snapshot.v20260114130428
@clerk/msw	0.0.1-snapshot.v20260114130428
@clerk/nextjs	7.0.0-snapshot.v20260114130428
@clerk/nuxt	2.0.0-snapshot.v20260114130428
@clerk/react	6.0.0-snapshot.v20260114130428
@clerk/react-router	3.0.0-snapshot.v20260114130428
@clerk/shared	4.0.0-snapshot.v20260114130428
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114130428
@clerk/testing	2.0.0-snapshot.v20260114130428
@clerk/ui	1.0.0-snapshot.v20260114130428
@clerk/upgrade	2.0.0-snapshot.v20260114130428
@clerk/vue	2.0.0-snapshot.v20260114130428

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

nikosdouvlis · 2026-01-14T22:53:14Z

!snapshot

clerk-cookie · 2026-01-14T22:55:12Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114225347
@clerk/astro	3.0.0-snapshot.v20260114225347
@clerk/backend	3.0.0-snapshot.v20260114225347
@clerk/chrome-extension	3.0.0-snapshot.v20260114225347
@clerk/clerk-js	6.0.0-snapshot.v20260114225347
@clerk/dev-cli	1.0.0-snapshot.v20260114225347
@clerk/expo	3.0.0-snapshot.v20260114225347
@clerk/expo-passkeys	1.0.0-snapshot.v20260114225347
@clerk/express	2.0.0-snapshot.v20260114225347
@clerk/fastify	2.6.9-snapshot.v20260114225347
@clerk/localizations	4.0.0-snapshot.v20260114225347
@clerk/msw	0.0.1-snapshot.v20260114225347
@clerk/nextjs	7.0.0-snapshot.v20260114225347
@clerk/nuxt	2.0.0-snapshot.v20260114225347
@clerk/react	6.0.0-snapshot.v20260114225347
@clerk/react-router	3.0.0-snapshot.v20260114225347
@clerk/shared	4.0.0-snapshot.v20260114225347
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114225347
@clerk/testing	2.0.0-snapshot.v20260114225347
@clerk/ui	1.0.0-snapshot.v20260114225347
@clerk/upgrade	2.0.0-snapshot.v20260114225347
@clerk/vue	2.0.0-snapshot.v20260114225347

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

Why: 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. What changed: - Added `satelliteAutoSync` option (defaults to true for backward compatibility) - When false, satellites skip handshake if no cookies exist and no sync trigger - Uses `__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

Why: Document the feature for changelog generation.

nikosdouvlis · 2026-01-16T12:20:41Z

!snapshot

clerk-cookie · 2026-01-16T12:22:50Z

Hey @nikosdouvlis - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260116122120
@clerk/astro	3.0.0-snapshot.v20260116122120
@clerk/backend	3.0.0-snapshot.v20260116122120
@clerk/chrome-extension	3.0.0-snapshot.v20260116122120
@clerk/clerk-js	6.0.0-snapshot.v20260116122120
@clerk/dev-cli	1.0.0-snapshot.v20260116122120
@clerk/expo	3.0.0-snapshot.v20260116122120
@clerk/expo-passkeys	1.0.0-snapshot.v20260116122120
@clerk/express	2.0.0-snapshot.v20260116122120
@clerk/fastify	2.6.9-snapshot.v20260116122120
@clerk/localizations	4.0.0-snapshot.v20260116122120
@clerk/msw	0.0.1-snapshot.v20260116122120
@clerk/nextjs	7.0.0-snapshot.v20260116122120
@clerk/nuxt	2.0.0-snapshot.v20260116122120
@clerk/react	6.0.0-snapshot.v20260116122120
@clerk/react-router	3.0.0-snapshot.v20260116122120
@clerk/shared	4.0.0-snapshot.v20260116122120
@clerk/tanstack-react-start	1.0.0-snapshot.v20260116122120
@clerk/testing	2.0.0-snapshot.v20260116122120
@clerk/ui	1.0.0-snapshot.v20260116122120
@clerk/upgrade	2.0.0-snapshot.v20260116122120
@clerk/vue	2.0.0-snapshot.v20260116122120

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

github-actions bot added clerk-js backend tanstack core-3 labels Jan 14, 2026

vercel bot deployed to Preview January 14, 2026 09:53 View deployment

vercel bot deployed to Preview January 14, 2026 09:58 View deployment

github-actions bot added the integration label Jan 14, 2026

vercel bot deployed to Preview January 14, 2026 11:02 View deployment

vercel bot deployed to Preview January 14, 2026 11:37 View deployment

vercel bot deployed to Preview January 14, 2026 11:44 View deployment

vercel bot deployed to Preview January 14, 2026 11:45 View deployment

vercel bot deployed to Preview January 14, 2026 12:12 View deployment

github-actions bot added nextjs astro labels Jan 14, 2026

vercel bot deployed to Preview January 14, 2026 12:35 View deployment

vercel bot deployed to Preview January 14, 2026 13:02 View deployment

vercel bot deployed to Preview January 14, 2026 22:27 View deployment

vercel bot deployed to Preview January 16, 2026 11:19 View deployment

nikosdouvlis force-pushed the nikos/satellites branch from 2e83741 to 3ea6d40 Compare January 16, 2026 11:20

vercel bot deployed to Preview January 16, 2026 11:20 View deployment

nikosdouvlis added 2 commits January 16, 2026 13:25

chore(repo): add changeset for satelliteAutoSync feature

03df463

Why: Document the feature for changelog generation.

nikosdouvlis force-pushed the nikos/satellites branch from 3ea6d40 to 03df463 Compare January 16, 2026 11:26

vercel bot deployed to Preview January 16, 2026 11:27 View deployment

nikosdouvlis changed the title ~~Improve satellite flows~~ feat(*): optimize satellite handshakes and introduce satelliteAutoSync prop Jan 16, 2026

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

Are you sure you want to change the base?

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

Conversation

nikosdouvlis commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

coderabbitai bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 14, 2026

Uh oh!

clerk-cookie commented Jan 14, 2026

Uh oh!

nikosdouvlis commented Jan 16, 2026

Uh oh!

clerk-cookie commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

nikosdouvlis commented Jan 14, 2026 •

edited

Loading

changeset-bot bot commented Jan 14, 2026 •

edited

Loading

vercel bot commented Jan 14, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 14, 2026 •

edited

Loading

coderabbitai bot commented Jan 14, 2026 •

edited

Loading