feat(upgrade): add satellite auto-sync codemod for core 3 migration #7653

nikosdouvlis · 2026-01-22T20:17:16Z

Why

Core 3 introduced satelliteAutoSync (defaults to false), changing satellite behavior. In Core 2, satellite apps always auto-synced on first visit. In Core 3, they don't unless satelliteAutoSync: true is explicitly set. Users upgrading need this prop added automatically to preserve existing behavior.

What changed

Add transform-satellite-auto-sync.cjs codemod that finds isSatellite usage (both JSX props and object properties) and adds satelliteAutoSync: true as a sibling
Skip if satelliteAutoSync is already present
Register the codemod for nextjs, react, expo, astro, and tanstack-react-start packages

Packages affected

@clerk/upgrade: New codemod + tests

Summary by CodeRabbit

New Features
- Automatic injection of satelliteAutoSync during Core 3 upgrades when satellite mode is detected for nextjs, react, expo, astro, and tanstack-react-start.
Tests
- Added comprehensive fixtures and tests validating the satellite auto-sync transformation across JSX and object configurations.
Documentation
- Added a changeset documenting the new codemod and its behavior.

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

Why: Core 3 changed satellite behavior — apps no longer auto-sync on first visit unless `satelliteAutoSync: true` is set. This codemod preserves Core 2 behavior by adding the prop wherever `isSatellite` is configured.

changeset-bot · 2026-01-22T20:17:20Z

🦋 Changeset detected

Latest commit: 650976b

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

This PR includes changesets to release 1 package

Name	Type
@clerk/upgrade	Minor

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-22T20:17:21Z

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 29, 2026 0:22am

pkg-pr-new · 2026-01-22T20:20:38Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 650976b

coderabbitai · 2026-01-22T20:26:15Z

📝 Walkthrough

Walkthrough

Adds a new codemod named transform-satellite-auto-sync that inserts satelliteAutoSync: true (or satelliteAutoSync={true} in JSX) when isSatellite is present in JSX attributes or object literals. Implements the transformer (parser set to tsx) at packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs, adds test fixtures and a Vitest/JSCodeshift test suite, registers the codemod in the Core 3 upgrade configuration, and includes a changeset documenting the addition.

🚥 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 'feat(upgrade): add satellite auto-sync codemod for core 3 migration' is fully related to the main changeset, which introduces a new codemod that automatically adds satelliteAutoSync: true during Core 3 migrations.

_{✏️ 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.}

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs`:
- Around line 6-47: The object transform in root.find(j.ObjectExpression)
currently finds isSatelliteIndex and unconditionally inserts satelliteAutoSync
at isSatelliteIndex + 1, which can be shadowed by a following spread; update the
logic to detect any SpreadElement/SpreadProperty (AST node representing ...obj)
after the isSatellite property: if a spread exists after isSatellite, either
skip the transform or insert the new j.objectProperty('satelliteAutoSync',
j.booleanLiteral(true)) before the first spread instead of at isSatelliteIndex +
1; adjust the check that uses isObjectPropertyNamed(...) and the insertion that
calls properties.splice(...) to use the computed safe insert index (or bail out)
so explicit property values are not overridden by spreads.

packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs

Ephem

I posted a question about false positives, but I think we are fine with that tradeoff and implementation looks good!

Ephem · 2026-01-26T18:54:18Z

packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs

Is adding satelliteAutoSync to every component and object that has a isSatellite overly broad, given there might be unrelated components/objects that also has it?

I get this is tricky to narrow down given props and objects can be passed around, is the idea that we'd rather have false positives than miss some?

Seems like an edge case, should still be safe and most people review the output after running a codemod anyway so I'm very fine with this, just wanted to double check this is the intent?

Thanks for the review Fredrik :) I thought about this as well and I decided that I could live with false positives given how impactful the change in behavior could be for apps migrating from Core 2 to Core 3. Happy to change this of course

Thinking more about this and your comment below, I decided to align the behavior and always add the prop at the end - I do think its important for as to override always, and let the end user decide in the very rare event that they have already added satelliteAutoSync manually (very unlikely as this prop will be introduced with core3)

Very true, sounds good to me! 🙏

packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs

Why: Ephem's review noted JSX and object transforms behaved inconsistently with spreads. JSX appended to end (codemod wins), objects inserted after isSatellite (spread could win). For an important migration, we want the codemod value to always apply so users explicitly review and remove if needed, rather than silently skipping. What changed: Object transform now uses push() instead of splice() to append satelliteAutoSync at the end, matching JSX behavior. Both transforms now consistently ensure the codemod value takes precedence over spreads.

github-actions bot added the core-3 label Jan 22, 2026

chore(upgrade): add changeset

b4d0d96

vercel bot deployed to Preview January 22, 2026 20:21 View deployment

coderabbitai bot reviewed Jan 22, 2026

View reviewed changes

packages/upgrade/src/codemods/transform-satellite-auto-sync.cjs Show resolved Hide resolved

Ephem approved these changes Jan 26, 2026

View reviewed changes

vercel bot temporarily deployed to Preview January 29, 2026 12:19 Inactive

Merge branch 'main' into nikos/satellite-auto-sync-codemod

650976b

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

nikosdouvlis merged commit 79a6cf2 into main Jan 29, 2026
38 checks passed

nikosdouvlis deleted the nikos/satellite-auto-sync-codemod branch January 29, 2026 12:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(upgrade): add satellite auto-sync codemod for core 3 migration #7653

feat(upgrade): add satellite auto-sync codemod for core 3 migration #7653

Uh oh!

nikosdouvlis commented Jan 22, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

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

edited

Loading

Uh oh!

coderabbitai bot commented Jan 22, 2026 •

edited

Loading

Walkthrough

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Ephem left a comment

Uh oh!

Ephem Jan 26, 2026

Uh oh!

nikosdouvlis Jan 29, 2026

Uh oh!

nikosdouvlis Jan 29, 2026

Uh oh!

Ephem Jan 29, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(upgrade): add satellite auto-sync codemod for core 3 migration #7653

feat(upgrade): add satellite auto-sync codemod for core 3 migration #7653

Uh oh!

Conversation

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

Uh oh!

Why

What changed

Packages affected

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 22, 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 22, 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 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ephem left a comment

Choose a reason for hiding this comment

Uh oh!

Ephem Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Ephem Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nikosdouvlis commented Jan 22, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

vercel bot commented Jan 22, 2026 •

edited

Loading

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

edited

Loading

coderabbitai bot commented Jan 22, 2026 •

edited

Loading