Prepare a Worklets patch release

Cuts a release of react-native-worklets from a stable branch (e.g. worklets-0.13-stable) in an isolated worktree: version bump via package scripts, pod lockfile regeneration, a release(Worklets): X.Y.Z PR, and a dry-run of the npm worklets publish workflow linked from the PR description. On explicit request it also runs the real npm publish (step 13) and creates the GitHub release with the published tarball attached (step 14).

Reference examples: PR #10598 (release(Worklets): 0.13.0) and PR #10469 (release(Worklets): 0.12.2).

Inputs

• Version — e.g. 0.13.1. Infer the branch from it: worklets-0.13-stable.
• Release branch — worklets-<X.Y>-stable.
• Optionally the cherry-pick tracking issue ("Worklets X.Y.Z cherry-pick thread") — verify every cherry-pick PR in it is merged before starting.

Naming conventions

Expected diff

These files, matching prior release commits:

• packages/react-native-worklets/package.json (version)
• packages/react-native-worklets/src/debug/jsVersion.ts (version)
• apps/fabric-example/ios/Podfile.lock (RNWorklets pinned to new version)
• apps/tvos-example/ios/Podfile.lock (same)
• The changelog (step 3a): packages/react-native-worklets/CHANGELOG.md, plus the deleted fragments in packages/react-native-worklets/changelog/ on stable branches newer than worklets-0.13-stable.

apps/macos-example/macos/Podfile.lock is not part of a release commit — see gotchas.

Procedure

1. Verify the branch tip

git fetch origin <release-branch>
git log --oneline -5 origin/<release-branch>

Confirm all expected cherry-picks are present (cross-check the tracking issue).

2. Worktree + install

git worktree add -b '@<you>/worklets/release-<version>' \
  ../rwr-release-<version> origin/<release-branch>
cd ../rwr-release-<version>
yarn install

yarn install is mandatory in a fresh worktree — workspace scripts and the pre-commit hook fail without it ("Couldn't find the node_modules state file").

3. Bump the version

yarn workspace react-native-worklets set-version --version <version>

Updates package.json and src/debug/jsVersion.ts, prints the previous version. Never hand-edit these.

3a. Update the changelog

On stable branches newer than worklets-0.13-stable, move the changelog fragments into CHANGELOG.md. The script needs gh to read the authors:

yarn workspace react-native-worklets changelog:squash <version>

If a fragment has no pr: N line, it reads the PR number from the first (#N) in the subject of the commit that added it. It fails when neither source gives a PR number. Then add a pr: N line to that fragment and run it again (see packages/react-native-reanimated/RELEASE.md).

worklets-0.13-stable and older have no fragments. There, move the ## Unpublished entries in packages/react-native-worklets/CHANGELOG.md under a new ## <version> — <YYYY-MM-DD> heading by hand, and keep the empty ## Unpublished section above it.

4. Build the packages

yarn build   # in the worktree root

Runs prepare-vscode and build-packages (builds react-native-reanimated, which builds Worklets and its Babel plugin as dependencies). Do this before build-apps.

5. Format and lint

yarn format
yarn lint

Both run across all workspaces (minutes — background them if needed). They must not change the working tree beyond the version bump — if format touches anything or lint fails, stop and investigate before committing.

6. Rebuild app pods

yarn build-apps   # in the worktree root; takes minutes — run in background

This runs build in common-app and every *-example workspace in parallel. Expected partial failure: on older stable branches macos-example fails the podspec compatibility assert (worklets_assert_minimal_react_native_version), because compatibility.json for the Worklets minor doesn't include the RN version react-native-macos pairs with. This failure predates the bump (the old version fails identically) and prior release commits ship without the macos lockfile — ignore it, but verify both iOS lockfiles did regenerate before the failure stopped the run:

grep 'RNWorklets (' apps/fabric-example/ios/Podfile.lock apps/tvos-example/ios/Podfile.lock

If they show the new version and git status shows only the expected files, proceed.

7. Commit and push

git add -A
git commit -m 'release(Worklets): <version>'
git push -u origin '@<you>/worklets/release-<version>'

8. Open the release PR

Open it ready-for-review (omit --draft); drafting is optional. The body is the minimal three lines below — no AI preamble (recent release PRs #10598 / #10469 don't carry one). The CI link is added in step 10.

gh pr create --base <release-branch> \
  --head '@<you>/worklets/release-<version>' \
  --title 'release(Worklets): <version>' \
  --body '## Summary

Releasing Worklets <version>'

9. Dispatch the publish workflow as a dry run

gh workflow run 'npm worklets publish' --ref '@<you>/worklets/release-<version>' \
  -f publish=false -f release-type=stable -f version=<version>

publish=false (also the default) maps to dry-run: true in the shared software-mansion/npm-package-publish action — the run packs the tarball and uploads it as an artifact but cannot publish. Never pass publish=true without an explicit user request.

Grab the run URL:

gh run list --workflow 'npm worklets publish' \
  --branch '@<you>/worklets/release-<version>' --limit 1 --json url,databaseId

10. Link the run in the PR description

gh pr edit fails in this repo with a GraphQL "Projects (classic)" deprecation error. Patch via REST instead:

gh api repos/software-mansion/react-native-reanimated/pulls/<N> -X PATCH -f body='...'

11. Verify the dry run

Wait for the run to complete (Monitor/poll gh run view <id>), then confirm in the job log:

• dispatch inputs show publish: false and the action received dry-run: true;
• the publish line ends with (dry-run): npm notice Publishing to https://registry.npmjs.org/ with tag <tag> and default access (dry-run);
• the tag is sane: legacy when releasing a patch for an older minor, latest for the current one (decided by should-be-latest.js).

jobid=$(gh run view <run-id> --json jobs --jq '.jobs[0].databaseId')
gh api "repos/software-mansion/react-native-reanimated/actions/jobs/$jobid/logs" | grep -e 'dry' -e 'Publishing to'

A dry run leaves no trace on the npm registry, so the workflow log is the authoritative evidence.

12. Smoke-test fabric-example (when asked)

Verify the release branch tip runs in development on both platforms, using argent (load argent-react-native-app-workflow first):

• Start Metro from the release worktree: yarn react-native start --port <port> in apps/fabric-example. 8081/8082 are often taken by other sessions — check with lsof -nP -i :<port> and pick a free one; never kill an existing Metro, it may belong to another active session.
• iOS: yarn react-native run-ios --udid <udid> --port <port> --scheme "Debug FabricExample", then xcrun simctl spawn <udid> defaults write org.reactjs.native.example.FabricExample RCT_jsLocation "localhost:<port>" and relaunch. A "React Native version mismatch" redbox whose native version matches another branch means a stale install survived (happens when the CoreSimulator session breaks mid-install) — reinstall-app from ios/Build/Products/Debug-iphonesimulator/FabricExample.app and re-apply RCT_jsLocation (reinstall clears it).
• Android: yarn react-native run-android --deviceId <serial> --port <port> --active-arch-only — gradle.properties pins all four ABIs, so always pass --active-arch-only for a single-emulator check. Then adb -s <serial> reverse tcp:8081 tcp:<port>.
• Verify: the examples list renders, an animation example actually animates (e.g. "Detach animated styles" or "Bokeh"), and globalThis._WORKLETS_VERSION_CPP (via debugger-evaluate) equals the release version.

13. Actual publish (separate, explicit step)

Only after the user reviews, merges the release PR, and explicitly asks: re-dispatch the workflow with -f publish=true (same release-type and version). Dispatch against the merged stable branch, not the release worktree branch — the release branch auto-deletes on merge, so --ref '@<you>/worklets/release-<version>' would fail with "ref not found":

gh workflow run 'npm worklets publish' --ref worklets-<X.Y>-stable \
  -f publish=true -f release-type=stable -f version=<version>

Verify the job log the same way as step 11, but the real-publish signature has no (dry-run) suffix:

• dry-run: false in the dispatch inputs;
• npm notice Publishing to https://registry.npmjs.org/ with tag <tag> and default access (no (dry-run)), followed by + react-native-worklets@<version>.

Never do this as part of preparing the release.

14. GitHub release (after publish)

The publish workflow only pushes to npm — it does not create the git tag or the GitHub release. Do that manually once published. Convention: release title Worklets - X.Y.Z, git tag worklets-X.Y.Z (see prior releases via gh release list).

git fetch origin worklets-<X.Y>-stable   # the merged release commit must be in the ref
sha=$(git rev-parse origin/worklets-<X.Y>-stable)   # FULL 40-char SHA — see gotcha
gh release create worklets-<version> --draft --target "$sha" \
  --title 'Worklets - <version>' \
  --generate-notes --notes-start-tag worklets-<previous-version>

• --target must be the full 40-char SHA. An abbreviated SHA returns HTTP 422: target_commitish is invalid.
• --generate-notes --notes-start-tag worklets-<prev> reproduces the ## What's Changed list plus the worklets-<prev>...worklets-<version> compare link, matching prior releases.
• For a patch of an older minor, add --latest=false. Only a release of the newest minor is marked as the latest release (for example, Worklets - 0.12.2 is not the latest release).
• Created with --draft; the worklets-X.Y.Z git tag is only created when the draft is published. Leave publishing the draft to the user unless they ask.

Attach the published tarball to the release:

npm pack react-native-worklets@<version>            # downloads the published .tgz
gh release upload worklets-<version> react-native-worklets-<version>.tgz

15. Cleanup (after the PR is merged)

xcrun simctl spawn <udid> defaults delete org.reactjs.native.example.FabricExample RCT_jsLocation   # only if you ran step 12
git worktree remove ../rwr-release-<version>
git branch -D '@<you>/worklets/release-<version>'

Confirmation checkpoints

• Before gh pr create — confirm version and branch tip contents if anything looks off (e.g. unexpected commits on the stable branch).
• Before any dispatch with publish=true — always; publishing is irreversible.

Gotchas checklist

• Fresh worktree without yarn install breaks workspace scripts and the pre-commit hook.
• yarn build-apps fails in macos-example on older stable branches — pre-existing compatibility gap, not caused by the bump; release commits ship without the macos lockfile.
• The final diff must be exactly the files listed above; anything else means the branch or build did something unexpected.
• publish=false is the workflow default, but pass it explicitly so the intent is visible in the run's inputs.
• gh pr edit is broken by the projectCards GraphQL deprecation — use gh api ... -X PATCH -f body=.
• Verify a dry run via the workflow log, not the npm registry.
• Branch names contain @ and the workflow name contains spaces — quote both in shell.
• npm tag: legacy for old-minor patches is correct, not a bug.
• Actual publish (step 13) must dispatch --ref worklets-<X.Y>-stable, not the release worktree branch — that branch auto-deletes on merge.
• The publish workflow does NOT create git tags or GitHub releases — that's the manual step 14.
• gh release create --target needs the FULL 40-char SHA; an abbreviated SHA returns HTTP 422 "target_commitish is invalid".
• Patches often target more than one maintained minor (e.g. current + previous, when the older line is still supported) — run this skill once per minor, each from its own worklets-<X.Y>-stable branch.