-
Notifications
You must be signed in to change notification settings - Fork 424
Improve satellite flows #7597
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Improve satellite flows #7597
Conversation
…dshake
Why:
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.
What changed:
- Added `satelliteAutoSync` option (default: true) to AuthenticateRequestOptions
- Added ClerkSyncStatus enum with NeedsSync ('1') and Completed ('2') values
- When satelliteAutoSync=false, skip handshake if no cookies and no sync trigger
- Use __clerk_sync=1 to trigger handshake after explicit sign-in action
- Use __clerk_sync=2 to prevent sync loops (overwrites NeedsSync using set())
- Backwards compatible: still reads legacy __clerk_synced=true param
…rk-js Why: Clerk-js needs shared constants and type definitions for the new satellite sync optimization feature to coordinate handshake flows on the client side. What changed: - Added CLERK_SYNC constant and CLERK_SYNC_STATUS enum to internal constants - Added CLERK_SYNC to valid query params list for proper cleanup - Added satelliteAutoSync option to ClerkOptions type with callback support - Deprecated legacy CLERK_SYNCED constant in favor of new unified param
Why: Client-side rendering needs to respect the satelliteAutoSync option to avoid unnecessary redirects when loading satellite apps in the browser. What changed: - buildSignInUrl/buildSignUpUrl add __clerk_sync=1 param for satellite redirects - #shouldSyncWithPrimary checks satelliteAutoSync option via handleValueOrFn - #redirectToSatellite uses __clerk_sync=2 instead of legacy __clerk_synced - #clearClerkQueryParams removes new CLERK_SYNC param - Backwards compat: still reads legacy __clerk_synced=true param
Why: TanStack React Start applications need to pass the satelliteAutoSync option through to the backend to control satellite handshake behavior. What changed: - Added satelliteAutoSync option to ClerkMiddlewareOptions type - loadOptions processes satelliteAutoSync using handleValueOrFn for callback support - Option is passed through to authenticateRequest
🦋 Changeset detectedLatest commit: 77bec92 The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
|
!snapshot |
📝 WalkthroughWalkthroughAdds multi‑domain synchronization using a new query parameter `__clerk_sync` with statuses `ClerkSyncStatus.NeedsSync = '1'` and `ClerkSyncStatus.Completed = '2'`, and a deprecated alias `__clerk_synced`. Introduces `satelliteAutoSync?: boolean` (default true) on public options and callbacks. Updates token/request handling, handshake and redirect logic, createRedirect signatures, client helpers, shared constants and query-param types, middleware/type signatures, loader options, and tests to support the new sync statuses and guards. 🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (6)
🧰 Additional context used📓 Path-based instructions (13)**/*.{js,jsx,ts,tsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.{js,jsx,ts,tsx,json,md,yml,yaml}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
packages/**/src/**/*.{ts,tsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
packages/**/src/**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.ts?(x)📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.{ts,tsx}📄 CodeRabbit inference engine (.cursor/rules/typescript.mdc)
Files:
**/*.{js,ts,jsx,tsx}📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Files:
**/*.{js,ts,jsx,tsx,json,md,yml,yaml}📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Files:
**/*⚙️ CodeRabbit configuration file
Files:
**/*.{test,spec}.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.{test,spec,e2e}.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Files:
**/*.test.{ts,tsx}📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Files:
🧬 Code graph analysis (3)packages/backend/src/__tests__/createRedirect.test.ts (1)
packages/backend/src/createRedirect.ts (2)
packages/backend/src/tokens/__tests__/request.test.ts (2)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (25)
🔇 Additional comments (10)
✏️ Tip: You can disable this entire section by setting Comment |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114095952 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114095952 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114095952 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114095952 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114095952 --save-exact |
Why: Integration tests needed to verify the satelliteAutoSync feature works correctly in a real Next.js middleware environment. What changed: - Updated test middleware to accept X-Satellite-Auto-Sync header - Added test: satelliteAutoSync=false skips handshake with no cookies - Added test: __clerk_sync=1 triggers handshake even with satelliteAutoSync=false - Added test: __clerk_sync=2 (completed) prevents re-sync loop - Added test: satelliteAutoSync=true (default) triggers handshake
Added examples for SSR (Next.js, TanStack Start), CSR (ClerkProvider), and dynamic callback usage.
…options Why: Allows dynamic configuration based on the request URL, matching the pattern used in Next.js middleware. What changed: - Added ClerkMiddlewareOptionsCallback type - clerkMiddleware now accepts options OR a callback function - Callback receives URL and returns options (sync or async)
|
!snapshot |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114114137 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114114137 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114114137 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114114137 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114114137 --save-exact |
Changed callback signature from `(url) => options` to `({ url }) => options`
for future extensibility.
|
!snapshot |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114114652 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114114652 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114114652 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114114652 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114114652 --save-exact |
Since clerkMiddleware now accepts a callback function for dynamic options, individual props no longer need to be callbacks. This simplifies the API. What changed: - Use MultiDomainAndOrProxyPrimitives instead of MultiDomainAndOrProxy - Remove handleValueOrFn usage from loadOptions - satelliteAutoSync is now just boolean (not callback) - domain, isSatellite, proxyUrl are now just primitives
…ellites Why: Server-side redirects (redirectToSignIn from middleware) weren't adding __clerk_sync=1 to the return URL for satellite apps. This broke the satellite → sign-in → primary → handshake flow when using SSR redirects, causing users to remain signed out on satellite domains. What changed: - Added isSatellite param to createRedirect in @clerk/backend - Pass isSatellite to createRedirect in nextjs and astro middleware - When satellite + cross-origin redirect, adds __clerk_sync=1 to returnBackUrl - Added tests for satellite sync param behavior
|
!snapshot |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114124449 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114124449 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114124449 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114124449 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114124449 --save-exact |
…ectUrl for satellites Why: Client-side redirects using forceRedirectUrl or fallbackRedirectUrl props (e.g., SignInButton with forceRedirectUrl) were not adding __clerk_sync=1 to the return URL. This caused the handshake to not trigger when returning from primary sign-in, leaving users signed out on satellite domains. What changed: - Added #addSyncTriggerToRedirectOptions helper that processes all redirect URL variants (signInForceRedirectUrl, signInFallbackRedirectUrl, etc.) - buildSignInUrl and buildSignUpUrl now apply sync trigger to all redirect options, not just the default redirectUrl
|
!snapshot |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114130428 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114130428 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114130428 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114130428 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114130428 --save-exact |
Replace __clerk_sync with __clerk_synced using false/true values: - __clerk_synced=false triggers sync (was __clerk_sync=1) - __clerk_synced=true means completed (was __clerk_sync=2) FAPI already returns __clerk_synced=true, so this unifies on a single param.
|
!snapshot |
|
Hey @nikosdouvlis - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260114225347 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/fastify@2.6.9-snapshot.v20260114225347 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260114225347 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260114225347 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260114225347 --save-exact |
Description
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
New Features
Chores
Tests
✏️ Tip: You can customize this high-level summary in your review settings.