Upgrade Rn Version

Upgrade RN Version

Flagship Code supports a React Native minor by carrying three things together: a native template, a dependency profile, and CLI registration. This skill covers adopting a new minor.

How to follow this skill

Every command below is written to run verbatim from the repository root. Run them as written.

• When this skill names a source of truth, read it. Do not infer a value from a neighbouring file, a previous version, or a sibling profile.
• Do not conclude that a step would pass. Run it and read the output.
• Do not substitute an equivalent command, a different directory, or one platform for another.
• If a step cannot be run, stop and report which step and why. A step you cannot run is a blocker, not a judgement call.

When to use this

A pending React Native minor needs adopting: a stable release above the newest version in packages/templates/react-native/. There is usually an open rn-adoption tracking issue for it.

Derive the target rather than accepting it. Compute the pending set as described in Ground truth at build time, take the lowest, and adopt that one. A version named in a request, an issue title, or a ticket is a check on your own derivation, not an instruction. If it is not the lowest pending minor, stop and report which one is. There may be a tracking issue open for every pending minor at once, so the presence of one for a later version is not permission to start there. Adopting out of order leaves the repository advertising support for a version whose predecessors were never adopted, which is the outcome this procedure exists to prevent.

Ground truth at build time

Do not trust cached version numbers in this doc. Re-derive at build time:

• Pending minors are stable React Native releases (npm view react-native versions --json, filtered to X.Y.0, never dist-tags) above the highest directory name in packages/templates/react-native/. Exclude anything npm marks deprecated (the guard against the accidental react-native@1000.0.0 publish, which otherwise looks like the newest pending minor).
• The currently-adopted minors are that directory listing itself. It is the support manifest; there is no separate manifest file.
• Latest patch per minor and its pairings (React, TypeScript, community CLI) come from that patch's own upstream package.json. Read it, do not assume.

Adopting one minor (one PR per minor, ascending)

Never adopt more than one version in a PR, never stack one adoption on another's unmerged branch, and never start the next version until the current one has merged.

1. Premise check. Run yarn install before anything else. The harvest script's codemods run through tsx, so against an uninstalled workspace they fail with Cannot find module 'typescript'; that is a missing install, not a broken script, and it is not a premise failure. Then confirm ./scripts/add-rn-version and the PR Compile and PR Test workflows already exist and work (throwaway-branch dry run). If tooling is genuinely missing or broken, that is a blocker on the tooling itself. Stop and report it; do not build or repair tooling as part of an adoption.

2. Harvest. Run ./scripts/add-rn-version 0.XX. This pulls the upstream @react-native-community/template (android and ios only) into packages/templates/react-native/0.XX/ and codemods: CLI registration (packages/cli-kit/src/@types/config.ts, packages/cli/src/ui/constants/messaging.ts), a shell dependency profile (packages/plugin-verify-dependencies/src/profile/0.XX.ts plus registration in index.ts), and the root package.json react-native pin. It does not touch the root react pin. Step 4 covers that; the script having run is not evidence the root is aligned.

3. Fill the profile. Spread the previous minor's profile, then reconcile every template-derived entry against this minor's own template. Do not assume an inherited value is still correct.

   • Source of truth: this minor's @react-native-community/template package.json (npm pack @react-native-community/template@<patch>). Diff it against the previous minor's, or read the same diff in the upgrade helper, to see what moved.
   • What to write: copy the template's version string verbatim, range operator included. An exact pin upstream ("A.B.C") means an exact pin in the profile ('A.B.C'); a range ("^A.B.C") stays that range. The operator is part of the pairing: React Native is tested against one patch of its react, and widening it lets a consumer resolve a react this minor was never built against.
   • One exception: react-native, and every @react-native/* entry the previous profile tracks, are written ^0.XX.0: the minor floor rather than the harvested patch. Take that set from the previous profile rather than from a list, because which scoped packages the template ships changes between minors. The profile-version test requires that literal form, because a profile must accept any patch of its own minor.
   • A tracked key that disagrees with the template is a bug, regardless of which minor introduced it. Inheritance carries stale pins forward silently, and some predate the minor you are adopting. Fix it in your minor and note it in the PR, or file it; do not propagate it.
   • Do not add tracking for packages prior profiles did not track (ecosystem-native libs like screens, gesture-handler, reanimated are not profile-tracked yet; see step 6). This applies to packages the template itself introduces: a scoped @react-native/* package appearing in the template for the first time is still an addition, and additions are not part of an adoption.
   • A tracked key with no counterpart in this minor's template carries forward untouched. Not every inherited entry is template-derived, and one that is not has nothing to reconcile against, so reconciling it is guesswork. Changing such a pin is separate work.
   • Earlier profiles are not the spec. The template is.

4. Align the workspace. The example and the repository root both carry React pins and they must agree. A root react range that admits a patch other than the example's exact pin resolves to two copies of React, and the example then fails at runtime rather than at build time.

   yarn workspace @brandingbrand/code-example flagship-code align-deps --profile 0.XX --fix
   yarn install

   Then set the existing react and react-native entries in the root package.json to the same strings this minor's profile carries, and run yarn install again. Edit the entries already declared there; do not add a new dependency block for them. Never hand-edit the example's pins; the profile drives those.

   Prove there is exactly one React before going further:

   yarn why react

   More than one resolved version is a failure. Fix the disagreeing pin and re-run. Do not continue with two.

5. Compile the example on both platforms. The iOS build runs pod install through prebuild; the Android build needs a JDK and the Android SDK. Your local toolchain has to match what .github/workflows/pr-compile.yml provisions: read its setup-node, setup-ruby, and setup-java steps and match the versions declared there rather than any version named in this document. A missing toolchain, or one on a different major version, is an environment blocker to report. It is not an adoption failure, and it is not something to install your way around.

   Run all four commands. These are the commands CI runs, so a failure here is a failure there.

   yarn workspace @brandingbrand/code-example prebuild --build internal --env prod --platform android --verbose
   cd apps/example/android && ./gradlew assembleDebug && cd ../../..
   yarn workspace @brandingbrand/code-example prebuild --build internal --env prod --platform ios --verbose
   cd apps/example/ios && xcodebuild -workspace app.xcworkspace -scheme app -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build && cd ../../..

   A passing test suite is not evidence that these pass, and no other step in the gate substitutes for them. A version is not adopted until it has compiled as a real app on both platforms.

6. Ecosystem-native pin breaks. If the example's compile fails because a non-profile-tracked dependency (screens, gesture-handler, reanimated, safe-area-context, async-storage, webview, community CLI) is incompatible with the new version, bump that one dependency's pin in the example (not the profile mechanism) and record why. The compile is what surfaces such a break instead of shipping a stale pin. Automating these pairings is separate, larger work, out of scope for an adoption PR.

7. Full local gate. Every command below, green, run in this order:

   yarn install
   yarn build
   yarn lint
   FLAGSHIP_CODE_TEST_RN_VERSION=0.XX yarn test --force

   Plain yarn test runs the plugin suites against the default 0.72 template; the environment variable points them at the version you are adding. Two things let that command pass without testing your version, so a green run here is not the proof:

   • If packages/templates/react-native/0.XX/ does not exist, the test environment resolves down to the nearest lower minor and passes against that one instead. Nothing reports the substitution.
   • test is a cached task and the variable is not part of its cache key, so a run following a plain yarn test can replay the earlier result. --force is what prevents that.

   The proof is the test-templates (0.XX) job on the pull request, which cannot exist unless the template directory does. The two native builds in step 5 are part of this gate and are not implied by these four commands.

8. Changeset. One file, message add support for react-native 0.XX, minor bump on the packages an adoption touches: code-plugin-verify-dependencies, code-templates, code-cli-kit, code-cli. Read the previous minor's changeset rather than this list if the two disagree. Declare another package only if this adoption actually modified it; do not declare one because it seems related.

9. PR. Draft from the first commit against develop. Mark ready once every item in the definition of done is satisfied, and request review from the repository's code owners. Carry the gate evidence in the PR description: the commands run, their results, and a link to the PR Compile run.