• Fast – ~10-50x faster depending on project
• Tree shaking – Smaller bundles means faster apps (21% smaller for init project)
• Compatible – Drop-in replacement for metro
• Configurable – Support for custom transformers and env variables

If this library helped you, please consider sponsoring.

yarn add react-native-esbuild esbuild

Make sure react-native.config.js exists in the root of your project, and create one if not. Add this library to the commands section like this:

// react-native.config.js
const { commands } = require('react-native-esbuild');

module.exports = {
  commands,
};

If you want to customize the esbuild configuration, for example by adding your own plugins you may do so with the createEsbuildCommands function:

// react-native.config.js
const { createEsbuildCommands, babelPlugin } = require('react-native-esbuild');

// See https://esbuild.github.io/api/#simple-options
const commands = createEsbuildCommands((config) => ({
  ...config,
  plugins: config.plugins.concat(
    babelPlugin({
      filter: /src\/my-babel-components\/.+\.[tj]sx?$/,
    })
  ),
}));

module.exports = {
  commands,
};

1. Open package.json in your editor and locate scripts section.
2. Edit start script to be react-native esbuild-start.
3. Prevent metro from starting automatically by appending --no-packager to the ios/android scripts.

{
  "scripts": {
    "android": "react-native run-android --no-packager",
    "ios": "react-native run-ios --no-packager",
    "start": "react-native esbuild-start"
  }
}

Set project.ext.react.bundleCommand to esbuild-bundle in android/app/build.gradle:

// android/app/build.gradle
project.ext.react = [
    enableHermes: false,
    bundleCommand: "esbuild-bundle",
]

1. Open your iOS project in Xcode manually or with xed ios
2. Select the Build Phases tab in your project settings.
3. Expand the Bundle React Native code and images section and add export BUNDLE_COMMAND=esbuild-bundle so it looks like this:

set -e

export BUNDLE_COMMAND=esbuild-bundle
export NODE_BINARY=node
../node_modules/react-native/scripts/react-native-xcode.sh

This library aims to be a plug-in replacement for the metro equivalent commands with the esbuild- prefix.

Esbuild doesn't natively support flow so such syntax needs to be stripped with a plugin. By default any file with @flow or @noflow pragmas will be stripped from flow, but you may also opt-in to flow stripping for more files by passing a custom flow syntax checker:

// react-native.config.js
const {
  createEsbuildCommands,
  defaultHasFlowSyntax,
  syntaxAwareLoaderPlugin,
} = require('react-native-esbuild');

const FLOW_MODULES_WITHOUT_PRAGMA = ['react-native-video', 'rn-fetch-blob'];

const commands = createEsbuildCommands((config, args) => ({
  ...config,
  plugins: config.plugins
    .filter((plugin) => plugin.name !== 'syntax-aware-loader')
    .concat(
      syntaxAwareLoaderPlugin({
        filter: /\.([mc]js|[tj]sx?)$/,
        cache: args.dev,
        hasFlowSyntax: (contents, filePath) =>
          defaultHasFlowSyntax(contents, filePath) ||
          FLOW_MODULES_WITHOUT_PRAGMA.find((m) =>
            filePath.includes(`node_modules/${m}/`)
          ),
      })
    ),
}));

module.exports = {
  commands,
};

Hermes doesn't support crucial ES6 features like block level scoping (let/const) and the team doesn't seem to want to merge this feature mentioning it being a too big of a change without having good enough reasons to add it.

Esbuild doesn't support Fast Refresh or Hot Module Replacement, but this library supports live reload instead.

MIT © Joel Arvidsson 2022-