# react-native-boost: a build time compiler that rewrites React Native code for speed

> react-native-boost is a Babel-based plugin and Metro wrapper that analyses React Native source at build time, moves work out of the runtime, and swaps JavaScript abstractions for native equivalents, all without imports in your own code. Its pitch is safe by default, and its constraint is that it needs React Native 0.83 or newer.

**kuatsu/react-native-boost** — ⚡️ The React Native performance compiler.

- Repository: https://github.com/kuatsu/react-native-boost
- Website: https://boost.kuatsu.de
- Stars: 580 · Forks: 14
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/kuatsu-react-native-boost

## The idea is to move work from the runtime into the compiler

react-native-boost describes itself as the React Native performance compiler. It analyses your app at build time and automatically applies safe performance optimizations across your React Native code, eliminating unnecessary runtime work, replacing JavaScript abstractions with more efficient native equivalents, and fixing common performance pitfalls without requiring you to rewrite your application code. The feature list makes the mechanism concrete. It does automatic build-time optimization, static source analysis that detects optimization opportunities before the app even runs, moves runtime work to build time by precomputing and simplifying work whenever it can be determined at build time, applies automatic performance fixes when they can be safely transformed, is safe by default in that optimizations are only applied when behavior can be preserved, keeps minimal runtime overhead because the optimizations happen entirely during compilation, and is compatible with most other ecosystem tools including Expo. The audience is a React Native team that has measured JavaScript overhead and would rather change the compiler than the components.

## It installs as a regular dependency, and the README insists on that

The installation step has one instruction that is easy to get wrong. The README asks you to install the package using your favorite package manager and says explicitly that you should not install the package as a development dependency. The reason is given. While the Babel plugin itself would work as a development dependency, it relies on importing the runtime library, `react-native-boost/runtime`, into your code, which requires the package to be installed as a regular dependency. The commands are:

```sh
npm install react-native-boost
# or
yarn add react-native-boost
```

The runtime import is the whole reason. A compiler that only ran at build time would be invisible to the bundler afterwards, but this one leaves something in the app that the app has to be able to resolve, and a package marked as a development dependency will not be present in a release build.

## The Metro configuration is the part that is not optional

After installing, Boost has to be wired into the bundler. The README calls this adding Boost to your Metro configuration, in `metro.config.js`:

```js
const { getDefaultConfig } = require('expo/metro-config'); // use `@react-native/metro-config` for non-Expo apps
const { withBoostConfig } = require('react-native-boost/metro');

module.exports = withBoostConfig(getDefaultConfig(__dirname));
```

The pattern is a standard Metro wrapper, where the default config is produced and then passed through Boost's own function. The inline comment matters for the majority of readers, since `expo/metro-config` is for Expo projects and `@react-native/metro-config` is the one for a plain React Native app, and getting them backwards is the first failure you will hit. If the file does not exist yet, the README tells you to generate it with:

```sh
npx expo customize metro.config.js
```

After that you restart the development server and clear the bundler cache with `npm start --clear`, or `yarn start --clear` for Yarn, and then the README states there is nothing else to do, with no imports in your code and no rebuilding required.

## Metro is the assumed bundler, and alternatives need their own setup

The README flags a boundary. If you are using Unistyles, Nativewind, or a bundler other than Metro, you are pointed to the documentation for setup instructions. That is a real constraint rather than a caveat, because the plugin's mechanism depends on the bundler pipeline to run the transformation. A project that has moved to a different bundler, or that uses Unistyles or Nativewind for styling, is not in the default path. The README also notes that the plugin is compatible with most other ecosystem tools including Expo, which is the case the install instructions are written for. Optional configuration is described in the documentation, with a page for configuring it. The repository also has a `benchmarks/` directory and a benchmark script, so the performance claims are reproducible by the project itself rather than being asserted only in prose.

## React Native 0.83 is the floor, and the 0.x line is a dead end

The compatibility table is short and worth reading carefully. The `0.x` line of react-native-boost is listed against all React Native versions, `1.x` against `>=0.83`, and `2.x` against `>=0.83`. The README states that current versions are compatible with all React Native versions since 0.83, and that runtime behavior is tested against all of them. For older React Native versions the advice is to install `react-native-boost@^0`, with the explicit warning that this version is not supported anymore and that, starting from React Native `0.80`, it prints import deprecation warnings from React Native. That last detail is a good sign of how the project is maintained. The warnings come from React Native itself rather than from the plugin, and the README chooses to document that rather than leave you to wonder whether the noise is coming from your own build. The release history shows the 2.x line moving quickly, with v2.0.1 on 2026-09-14, v2.0.2 on 2026-09-18, and v2.0.3 on 2026-10-02.

## Safe by default is a promise about behavior, not about speed

Two of the feature claims are really one claim stated twice. The optimizations are only applied when behavior can be preserved, and the automatic fixes apply when they can be safely transformed. That is the right framing for a tool that rewrites your source without asking, and it is also the claim you would want tested rather than believed. The benchmark section in the README points to a comparison of iOS frame rate against render load, and it directs you to the benchmarks page for Android results and the full methodology, which is the right place to look before drawing conclusions. The repository structure backs the claim up in a practical way. There is an `apps/` directory holding the documentation site, a `benchmarks/` directory, a `packages/` directory for the published packages, and a `tooling/` directory, and the root `package.json` is a private pnpm workspace that runs the package build, typecheck, and test across all packages in parallel, with a benchmark script that runs a TypeScript CLI through tsx.

## A single agency built it, and the tooling reflects that

The README notes that react-native-boost is built at Kuatsu, described as a boutique React Native agency specialised on building highly performant React Native apps. The repository layout is a modern JavaScript monorepo built on pnpm, with a pnpm workspace file, a pnpm lockfile, husky for git hooks, commitlint with a conventional config, oxlint for linting and oxfmt for formatting, and a TypeScript pinned to about 7.0. The `packages/` directory holds the runtime and the plugin, and `apps/` holds the documentation site and an example app, since the root scripts include an `example` script that runs the react-native-boost-example package and a `dev` script that runs the plugin and the example together. The monorepo also carries an `AGENTS.md`, a `CODE_OF_CONDUCT.md`, and a `CONTRIBUTING.md`. The last point to weigh is the obvious one. A tool whose transformations are applied for you by default is one where a bug in the transformation affects every component in your app, and a single-vendor origin with a small team behind it is worth factoring into that risk.

## Conclusion

react-native-boost fits a React Native team that has profiling data pointing at JavaScript overhead rather than at the native layer, and that wants the fix applied at build time instead of hand-rewriting components. It is the wrong tool if you are on React Native older than 0.83, since the 0.x line is unsupported and prints import deprecation warnings, and it is the wrong tool if you need per-component control, because the plugin applies its own rules rather than accepting a directive. Before you adopt it, read the compatibility table and the benchmarks page methodology, install it as a regular dependency rather than a development dependency as the README insists, and confirm your bundler is Metro, since Unistyles, Nativewind, and other bundlers need separate setup.

## FAQ

### How do I install react-native-boost?

Run `npm install react-native-boost` or `yarn add react-native-boost`. The README asks that you do not install it as a development dependency, because the Babel plugin imports the runtime library `react-native-boost/runtime` into your code and that needs the package present at build time.

### How do I add react-native-boost to my Metro configuration?

In `metro.config.js`, require `getDefaultConfig` from `expo/metro-config` or `@react-native/metro-config` for non-Expo apps, require `withBoostConfig` from `react-native-boost/metro`, and export `withBoostConfig(getDefaultConfig(__dirname))`. If the file is missing, run `npx expo customize metro.config.js` first.

### Which React Native versions does react-native-boost support?

Current versions are compatible with all React Native versions since 0.83, and runtime behavior is tested against all of them. The `1.x` and `2.x` lines require `>=0.83`, while `0.x` works with all versions but is unsupported and prints import deprecation warnings from React Native starting at version `0.80`.

### Does react-native-boost work with Expo and other bundlers?

The README lists compatibility with most other ecosystem tools including Expo, and the install instructions use `expo/metro-config`. If you use Unistyles, Nativewind, or a bundler other than Metro, the README points to the documentation for separate setup instructions.

### Do I need to change my application code to use react-native-boost?

No. The README states that after the install and Metro configuration there is nothing else to do, with no imports in your code, no rebuilding, and no other step required. Optional configuration is described in the documentation.

## Sources

- [kuatsu/react-native-boost on GitHub](https://github.com/kuatsu/react-native-boost)
- [License: MIT](https://github.com/kuatsu/react-native-boost/blob/main/LICENSE)
- [Project website](https://boost.kuatsu.de)
- [README](https://github.com/kuatsu/react-native-boost/blob/main/README.md)
- [Releases](https://github.com/kuatsu/react-native-boost/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kuatsu-react-native-boost