CLI tool
react-native-community/upgrade-helper avatar
react-native-community/upgrade-helper

upgrade-helper diffs two pristine templates, not your project

⚛️ A web tool to support React Native developers in upgrading their apps.

4,074 stars129 forksTypeScriptMIT

At a glance

What is it?
The upgrade helper answers one question: what changed between the version you are on and the version you want, as expressed in the project template the framework's own generator produces. That design choice is stated in a block quote in the readme and it is the most important thing about the tool, because it means the diff is always clean and always in sync with the release, and it also means the changes to your own code are yours to make. Everything else is presentation and convenience on top of that diff.
Who is it for?
The tool suits a developer planning a version jump who wants the complete list of template changes before touching a single file, and who will still read the release notes. It does not suit someone expecting it to patch their code, because the input is two generated projects rather than your repository.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 115 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • react-native-community/upgrade-helper4,074 ★ · +2
Star history
Repository2026-09-242026-11-15
react-native-community/upgrade-helper4.1k4.1k

2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The input is two generated projects, which is the whole design

The how it works section quotes its own upstream project, and the quotation is the specification. The diff source repository exposes an untouched application generated by the framework's own initialisation command, and each new release causes a fresh project to be created while the old one is removed, so what is compared is always two clean trees. The stated consequence is that the diff is always clean and always in sync with the changes to the initialisation template. The benefit follows directly: you see everything the release changed in the template, which is the part most people miss when they read release notes. The cost is equally direct, and the readme does not pretend otherwise: this shows you what you need to change in your code, but it is you who makes the changes.

Six conveniences sit on top of the diff

The extra features are listed as a short set and each one solves a specific irritation. Inline comments appear next to files to give more insight about what a particular change means, which is the part a raw diff cannot tell you. A set of links points at further explanations for the version you are upgrading to, so the tool is a way into the notes rather than a replacement for them. Each file has a done button next to it, which turns a long file list into a checklist. New binary files get a download button instead of a broken diff. And holding the alt key while clicking an expand control toggles every file at once, which is the difference between reviewing forty files and two. The list ends by pointing at an enhancement label, so the feature set is a work in progress rather than a fixed scope.

Running it locally is five steps and one button

The contribution section is a contributor walkthrough, and it is short enough to be the fastest way to see what the tool does. Fork the project, clone it, install the dependencies, start it, and open the local address. Then two UI steps: choose a starting version and a target version, and press the button that asks to be shown how to upgrade. That is the entire interaction model of the tool, and knowing it before you deploy to a live site is worth the two minutes. After that you branch, make your change and open a pull request against the repository using the provided template, so the project treats the readme walkthrough as the definition of done for a local environment.

The build is a forked application generator held open by rewiring

The manifest shows what the project is built on, and it is worth decoding. The scripts are all wrapped in a rewire tool with an environment flag that tells the underlying generator to keep its lint configuration, so this is an application created by the standard React toolchain that has been patched rather than replaced. The configuration file that performs that patching sits at the repository root, and the base version of the toolchain is pinned. That combination is a deliberate maintenance choice: the project wanted the convenience of a preconfigured build without giving up control of its lint step, and it kept the version of the manifest itself at a placeholder, which tells you releases of this web tool are not tracked as package versions. Two instruction files for coding agents sit at the root beside the human contributor guide, so the repository is written for both kinds of contributor.

End to end tests run in a container built on a browser image

The test story is the most elaborate part of the repository. The container image is a prebuilt browser automation image, and the first thing the recipe does is install a colour emoji font, with a comment that says plainly why: the screenshots were not loading the emoji. The dependency install is pinned to the lock file, and the compose file defines a single service that mounts the source directory, the test directory, the manifest and the lock file, and then runs the end to end script. That script starts the development server and waits for it, polling the local address with retries and timeouts rather than sleeping a fixed number of seconds. The unit test script deliberately excludes the end to end files with a pattern, so the two suites never run in the same invocation.

The dependency list is a component kit and a diff renderer

Reading the runtime dependencies tells you what the interface is made of. There is a full component suite with its icon set, a styling layer built on the emotion runtime, an animation library, a markdown to component converter, and the diff viewer that renders the actual content. Then the small utilities that show up in every browser tool: a query string parser, a semantic version library, a persisted state hook, a content loading placeholder, a copy to clipboard helper, a confetti component, an analytics wrapper, and a button that renders a GitHub star count. The React version is pinned exactly, and the diff viewer is on a caret range, which is the one dependency where the project seems willing to accept drift.

A static site, a covenant, and no releases at all

Three closing facts. The tool is published as a static site on the community's documentation hosting, which is why the readme's only call to action is a link labelled with an invitation to open it, and why the local walkthrough exists for contributors rather than for users. The repository has no published releases, so there is no version to pin and the manifest version is a placeholder, which is consistent with a tool deployed by pushing to the branch. And the licensing is a permissive one with a separate code of conduct document adopting the contributor covenant, which the readme states all contributors are expected to follow. The last push to the default branch is dated 2026-07-23 on a repository that is not archived.

Editorial conclusion

The tool suits a developer planning a version jump who wants the complete list of template changes before touching a single file, and who will still read the release notes. It does not suit someone expecting it to patch their code, because the input is two generated projects rather than your repository. Before relying on it, check that both the version you are leaving and the version you are entering are supported by the tool, and expect the download button to be the only part of the flow that touches your machine.

Frequently asked questions

What is upgrade helper?

A web tool that helps React Native developers upgrade their app. It shows the full set of changes between any two versions, computed by diffing two untouched projects generated by the framework's own init command, plus inline comments, links to explanations, a done button per file and download buttons for new binary files.

How do I use react native upgrade helper?

Open the tool, pick a starting version and a target version, and press the button that shows how to upgrade, then work through the changed files using the done button on each to track progress. To run it locally instead, clone, install dependencies, start it, open the local address and pick the two versions there.

How do I upgrade my React Native project to a new version?

Use the upgrade helper to see everything that changed in the project template between your current version and the target, then apply those changes to your own code, reading the release notes the tool links to. The tool does not patch your repository: its input is two freshly generated projects, not your source.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/react-native-community-upgrade-helper.svg)](https://hysenlabs.com/projects/react-native-community-upgrade-helper)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/react-native-community-upgrade-helper.svg)](https://hysenlabs.com/projects/react-native-community-upgrade-helper)

Was this useful?