rn-diff-purge: reading a React Native upgrade as a diff between two clean templates

One branch per release, each holding a clean scaffold

rn-diff-purge is a repository that exposes an untouched React Native app generated with the CLI command `npx @react-native-community/cli init RnDiffApp`.

The mechanism is simple and it is the whole design. Each new React Native release causes a new project to be created, removing the old one, and getting a diff between them. The consequence is stated plainly: the diff is always clean, always in sync with the changes of the init template.

A dedicated branch per release makes changes very easy to watch. The README gives the pattern with concrete comparisons, and the annotations are what make the table readable. A comparison between `release/0.28.0` and `release/0.29.0` is labelled as a change in the Android template. A comparison between `release/0.29.0` and `release/0.29.2` is labelled as no change. A comparison between `release/0.30.0` and `release/0.31.0` is labelled as a minor change in `.flowconfig`.

Those three examples say something important about the project. Most release-to-release comparisons change nothing at all, some change one configuration file, and a minority change the Android template substantially. A developer reading a diff of their own project cannot tell which category they are in, because their project has diverged. Reading the template diff tells them directly.

The licence is MIT, with the `LICENSE` file at the repository root, and the repository is not archived with the last push on 2026-10-14. The project lives under the `react-native-community` GitHub organisation, and its homepage is the upgrade helper at react-native-community.github.io/upgrade-helper, which is where the published diff table is rendered.

The published table, and why the cell letters matter

The main artefact is the diff table, published at react-native-community.github.io/rn-diff-purge, and it is designed to be read rather than computed.

The table has a From-to column and then a set of narrow columns, each headed by a single letter. Reading the header, the letters spell out the parts of a React Native project that can change: R, N, C, O, R, E, T, E, A, M, which is to say the Android and iOS project templates, the C, O and N pieces of the configuration, the Metro bundler setup, the entry point and the EAS build configuration.

Each cell contains a symbol. An X marks a version pair that is not comparable, and a dash marks a pair with no relevant change. When a cell contains a link, it points at the GitHub compare view for that specific pair of release branches, which is where the actual diff lives.

The table is the point of the project for most users, and the README has a section asking for help to make this full table pretty and more useful, with concrete suggestions such as alternating row colours, keeping the leftmost column on top and always visible, and a column width that fits the content in one line.

So the project has two audiences. One wants the raw compare URLs, which the table and the branch structure give. The other wants to know at a glance whether a given upgrade touches the Android template, the iOS template, the JavaScript configuration, the bundler setup or the build configuration, and for that the table is the interface.

The table covers a long history, with entries going back through the 0.28 era and forward to the 0.88 release candidates, which is what makes it useful for someone several versions behind.

Why not just diff my own project

The README points at a discussion thread for the reasoning, and the argument is worth reconstructing because it explains the trade-off the project accepts.

The default way to see what changed in a React Native release is to look at the release notes and the template changes, and then work out which of those apply to your own project. The rn-diff way, which this project describes itself as better than, is to keep an incrementally updated project and diff that. The problem with an incrementally updated project is that the diff accumulates every change you made on top of the template, so the comparison is between your project and the new template, and you cannot tell which differences are yours and which are the release's.

Purge solves that by throwing away the accumulated state on every release. The cost is that the branch holds a project that was scaffolded fresh, so the diff shows exactly the template delta and nothing else.

The alternative, which is what many teams do, is to scaffold a fresh project yourself with the CLI at the version you want and diff it against your own tree. That gives you the same information and needs no repository at all. What the repository adds is the history, the per-release branches, and the table that maps release pairs to the specific part of the project that changed, so you do not have to construct the comparison yourself for the version pair you care about.

That is the real value proposition, and it is a modest one. It is a convenience and a reference, not a dependency. Nothing in your project imports from it.

The scripts that regenerate the branches

The repository is a small Node.js project, and the `scripts/` directory holds the automation that creates the per-release branches.

The `package.json` shows the dependency set, and it tells you what the tooling does. `octokit` is the GitHub API client, and it is a dev dependency, so the generation scripts talk to GitHub to create branches and push commits. `replace-in-file` is the other dev dependency, used to rewrite content in files.

The runtime dependencies are `get-stdin` for reading piped input, `markdown-table` and `markdown-to-html` for generating the table, `ramda` for functional data manipulation, and `semver` for version comparison, which is what makes sense when the whole project is about ordering and comparing release versions.

The `scripts/` directory in the repository root is where the generation logic lives, and the `docs/` directory holds the documentation.

The repository also has a `.yarn/` directory with a `.yarnrc.yml`, and the `packageManager` field pins `[email protected]`, so the project uses Yarn's modern release rather than npm. The `mise.toml` file at the root pins the toolchain version, and there is a `prettier.config.cjs` for formatting, which is consistent with a repository where the generated content has to stay formatted.

The other root files are worth noting because they describe the project's governance. There is an `AUTHORS` file, a `README_MAINTAINERS.md` that is separate from the main README, a `RELEASES` file, and a `USAGE.md`.

One inconsistency is worth flagging. The repository's licence is reported as a custom one that GitHub cannot classify, and the root has a `LICENSE` file, while the `package.json` declares `"license": "ISC"`. The README and the file at the root are what govern, and the metadata disagrees with them.

What the project cannot tell you about your upgrade

There is a clear limit to the diff, and it is the limit of the approach rather than a gap in the implementation.

The branches hold the template and nothing else. They say what the CLI generates for a new project at a given version. They do not say what happens to a project that has added a native module, because that library has its own build configuration, its own Gradle or CocoaPods setup, and its own version of the React Native headers, and none of that appears in a template diff.

So the tool tells you exactly what the framework changed and nothing about what your dependencies need. For a project whose only native dependency is the standard set, the template diff is most of the story. For a project with a camera library, a push notification library, a background job library and a payments library, the diff is one input among several, and the hard part of the upgrade is in the parts the diff cannot show.

There is a second limit in the table's own coverage. It compares the template across release versions, and it does not track your branch point. If your project is on a release candidate, the table's X entries mark the pair as not comparable, and the useful comparison for you is between the last stable you used and the version you are moving to.

What the project does give you is a way to answer one specific question quickly: what did the template change between the version I am on and the version I want, and which part of my project does that touch. That is a question worth answering before an upgrade, and the table answers it in one page.

The hosting is the other practical detail. The table and the upgrade helper are published as static pages on GitHub Pages from the same repository, so what you read is generated from the branches, and a stale table is a stale generator rather than a stale table.

Editorial conclusion

rn-diff-purge fits a React Native developer upgrading across a minor or major release who needs to know exactly what the template changed, rather than inferring it from their own modified project. It does not fit a team whose upgrade path is blocked by third-party native dependencies, because the repository only shows the template and says nothing about how a library with its own build steps reacts to a new React Native version. Verify first that the release you are moving to has a branch in the comparison table, that the diff you read matches the template version your project was scaffolded from, and that the packaged CLI-initiated project you compare against is the same generator version, since the whole premise is that the diff stays in sync with the init template.

Frequently asked questions

Official sources

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