react-native-esbuild

0.6.0 verified Fri May 01 auth: no javascript

A fast bundler and dev server for React Native that leverages esbuild instead of Metro. Current stable version is 0.6.0, with updates supporting React Native 0.72. Typically released every few months. Key differentiators: 10-50x faster bundling, tree shaking resulting in ~21% smaller bundles, drop-in replacement for Metro, support for custom transformers and environment variables. Peer dependencies include @babel/core >=7.0.0 and esbuild >=0.17. Compatible with out-of-tree platforms (macOS, Windows) and offers interactive mode.

Common errors

error Error: Cannot find module 'react-native-esbuild' ↓

cause Package is not installed or not in node_modules.

fix

Run 'yarn add react-native-esbuild esbuild' or 'npm install react-native-esbuild esbuild'.

error TypeError: commands is not iterable ↓

cause Incorrectly importing commands as an array instead of an object with a commands key.

fix

Use correct import: const { commands } = require('react-native-esbuild'); not import commands from 'react-native-esbuild';

error error: No platform specified ↓

cause Missing --platform argument in esbuild-bundle.

fix

Add --platform android or --platform ios to the bundle command.

error Error: esbuild version must be >=0.17 ↓

cause Outdated esbuild version installed.

fix

Update esbuild to >=0.17: 'yarn upgrade esbuild --latest' or 'npm install esbuild@latest'.

Warnings

deprecated esmCustomMainFieldResolverPlugin is deprecated and no longer needed with esbuild >= 0.17. ↓

fix Remove usage of esmCustomMainFieldResolverPlugin; esbuild 0.17+ handles main fields automatically.

gotcha The dev server must be started with 'react-native esbuild-start' instead of 'react-native start' (Metro). Using the wrong command will launch Metro instead of esbuild. ↓

fix Update package.json scripts: change 'start' script to 'react-native esbuild-start' and ensure --no-packager is appended to ios/android scripts.

breaking Version 0.4.0 introduced a flow/reanimated syntax-aware loader that may change behavior for files containing Flow or Reanimated code; previous versions may have failed silently. ↓

fix If using Flow or Reanimated, ensure your files are properly annotated; the loader now actively processes these syntaxes and may throw errors for malformed code.

gotcha Source map support was fixed in 0.4.0; earlier versions experienced crashes related to source maps. ↓

fix Upgrade to 0.4.0 or later to avoid source map crashes.

breaking Support for out-of-tree platforms (macOS, Windows) was added in 0.3.0; previous versions only supported iOS and Android. ↓

fix If using Windows or macOS targets, upgrade to 0.3.0 or later.

Install

npm install react-native-esbuild

yarn add react-native-esbuild

pnpm add react-native-esbuild

Imports

commands
wrong
```
import { commands } from 'react-native-esbuild';
```
correct
```
const { commands } = require('react-native-esbuild');
```
CommonJS require is standard for react-native.config.js; ESM import may not work depending on Node configuration.

createEsbuildCommands

wrong

import createEsbuildCommands from 'react-native-esbuild';

correct

const { createEsbuildCommands } = require('react-native-esbuild');

Named export; default import does not work.

babelPlugin

wrong

const babelPlugin = require('react-native-esbuild/babelPlugin');

correct

const { babelPlugin } = require('react-native-esbuild');

babelPlugin is a named export from the main entry, not a separate file.

Quickstart

Shows how to configure react-native-esbuild as a CLI plugin, with optional custom esbuild configuration and Babel plugin, then run start or bundle commands.

// Configure react-native-esbuild as a CLI plugin
// File: react-native.config.js
const { commands, createEsbuildCommands, babelPlugin } = require('react-native-esbuild');

// Option 1: Use default commands
module.exports = { commands };

// Option 2: Customize with createEsbuildCommands
const customCommands = createEsbuildCommands((config) => ({
  ...config,
  plugins: config.plugins.concat(
    babelPlugin({
      filter: /src\/my-babel-components\/.+\.tsx?$/
    })
  )
}));

module.exports = { commands: customCommands };

// Then run:
// npx react-native esbuild-start --port 8081
// npx react-native esbuild-bundle --platform android --dev false