React Native Upgrade Helper: reading the diff between two RN templates

The problem: your app is not the template it started from

A React Native app is generated from an init template, then edited. Every release changes that template: build files, native project files, Metro configuration, package.json entries. The release notes describe behaviour, not the exact edits to the template, and your app has diverged from the template since the day you ran the init command. So the practical question during an upgrade is not "what changed in React Native" but "what changed in the files I inherited, and which of those changes do I still need to apply?".

Upgrade Helper answers that second question. It is aimed at developers maintaining a bare React Native app who upgrade on their own schedule, one version at a time, and who need to reconcile their tree with the new template. It is a browser tool, not a CLI, and it does not touch your repository.

Where the diff comes from: rn-diff-purge, not your project

The README is explicit that the tool is "based on the previous work done in the rn-diff-purge project". That project, in the README's words, exposes "an untouched React Native app generated with the CLI react-native init RnDiffApp", and each new React Native release creates a new project, removes the old one, and produces a diff between them. The stated result is a diff that is "always clean, always in sync with the changes of the init template".

That is the whole data flow. Two clean templates go in, one diff comes out, and the web app renders it. Nothing in the pipeline inspects your app, your package.json, or your native folders. This is the single most important thing to understand about the tool: the diff is a property of two React Native versions, not of your project. If your app never modified a given file, the diff tells you exactly what to do. If it did modify that file, the diff is an input to a manual merge, and the merge is yours.

The rendering layer is react-diff-view, and the app itself is a create-react-app project (the scripts still run through react-app-rewired), acknowledged in the README alongside rn-diff-purge.

Running Upgrade Helper locally with yarn and Docker

Most people use the hosted version at the project's GitHub Pages URL. The README also documents a local path, which is what you need if you want to test a change or run the end-to-end suite. The contributing steps are: clone the project, install, start, open the dev server, pick the two versions, and click the button.

git clone https://github.com/react-native-community/upgrade-helper.git
cd upgrade-helper
yarn install
yarn start

The dev server listens on port 3000, so you open http://localhost:3000 in a browser. On that page you select a starting version and a target version, then click the button labelled "Show me how to upgrade". What you get is the file-by-file diff between the two templates, with per-file controls.

If you prefer the container path, the repository ships a Dockerfile based on buildkite/puppeteer and a docker-compose.yml whose tests service runs the end-to-end suite:

yarn test-e2e

That expands to docker-compose run tests, which builds the image and runs yarn docker-test-e2e inside it. The Dockerfile also installs fonts-noto-color-emoji so emoji render correctly in the browser used by the tests. This path is for contributors, not for people upgrading an app.

The features that make a long diff readable

A raw diff between two React Native templates is large, and most of it is noise for any given upgrade. Upgrade Helper adds several things on top of the diff view, all listed in the README: inline comments giving more insight about precise files, a set of links with further explanations about the version you are upgrading to, a "done" button next to each file so you can track your own progress through the list, a download button for new binary files, and the ability to toggle all files by holding the alt key while clicking expand or collapse.

The done-button state is the one that matters in practice, because an upgrade is a multi-hour manual pass and the tool is the checklist. The binary download button exists because a diff cannot show you the contents of a changed image or asset, only that it changed. The alt-click toggle is a small thing that saves a lot of clicking on a diff with dozens of files.

None of these features write to your project. The tool produces a reading surface and a progress list; the edits happen in your editor.

What it will not do, and when it is the wrong tool

Upgrade Helper does not upgrade your app. There is no command that applies the diff, and the README does not document rollback, dry-run, or any write path into a user's repository. You read the diff and you make the edits. Anyone looking for a codemod or an automated migration will not find one here.

Second, the tool can only show versions that exist in the rn-diff-purge data. If a React Native release has not been turned into a template diff yet, there is nothing for the web app to render for that version, and the version list is the place where that shows up. That is a dependency you do not control and cannot work around from the UI.

Third, the diff describes the init template. If your app has already diverged, applying a template change verbatim can be wrong: the same file may have been restructured, and the diff has no knowledge of that. Read each hunk against your own file before pasting it.

Finally, this is a bare-workflow tool. For an Expo-managed project the relevant change is usually in the Expo SDK and its config, not in the React Native template files, so the diff has less to say about your upgrade path.

How it compares with the upgrade CLI and the release notes

The nearest alternative is the react-native upgrade command shipped with the CLI, which attempts to apply template changes to your project directly. The difference is exactly the one described above: the CLI writes to your tree and leaves you to resolve the conflicts it creates, while Upgrade Helper writes nothing and leaves you to make the edits with the diff in front of you. If your app is close to the template, the CLI is faster. If your app has diverged, the CLI's conflicts are the work, and the diff view is the more honest starting point.

Release notes are the other thing people reach for. They tell you what changed and why, in prose, across the whole release. Upgrade Helper tells you which files changed and how, in the template only. These are complementary: the tool links out to further explanations for the target version, which is the bridge between the two.

Maintenance, licence and the cost of keeping it useful

The repository is not archived, and the last push was on 2026-07-23. The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept with the code. That is a plain permissive licence with no copyleft obligation on your app; it says nothing about the licence of the React Native template diffs the tool displays, which come from rn-diff-purge.

The upgrade cost is mostly not in this repository. The tool's usefulness tracks rn-diff-purge: when a new React Native version is released, a new template diff has to exist before the web app can show it. The dependency list in package.json is pinned in places (react 18.2.0, react-dom 18.2.0, react-scripts 5.0.1, markdown-to-jsx 7.1.9) and caret-ranged in others (antd ^5.14.0, react-diff-view ^3.2.0), so a contributor working on the tool inherits the usual React app maintenance surface. For a user of the hosted site, the maintenance cost is zero until the version you need is missing.

Editorial conclusion

Adopt Upgrade Helper if you maintain a bare React Native app and need to see which template files changed between two versions before you touch your own code. Skip it if you expect it to modify your project, or if your app is Expo-managed and the change you need lives in the Expo SDK rather than the RN template. Before relying on a diff, open the tool, set the two versions, and confirm that the target version appears in the version list; if it does not, the underlying rn-diff-purge data has not been generated for it yet and there is nothing to read.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. react-native-community/upgrade-helper on GitHub
5. README