metro-minify-esbuild

0.2.0 verified Mon Apr 27 auth: no javascript

ESBuild-based minifier plugin for Metro bundler, primarily used in React Native and Expo projects. Version 0.2.0 requires esbuild as a peer dependency. It replaces the default uglify-es minifier to improve bundle times — up to 3x faster in large projects — while producing comparable bundle sizes (typically within 7KB of uglify-es). Unlike full transpilation with ESBuild, this plugin only handles minification, preserving compatibility with Babel plugins (e.g., Reanimated, decorators). Released by Evan Bacon and used in Expo tooling. Active maintenance with infrequent releases.

Common errors

error error: Invalid option in transform() call: "mangle" ↓

cause Metro passes default uglify options which include 'mangle'.

fix

Set config.transformer.minifierConfig = {} (or a valid esbuild options object) in metro.config.js.

error Error: Cannot find module 'metro-minify-esbuild' ↓

cause Package not installed or require.resolve path is incorrect.

fix

Run 'yarn add -D metro-minify-esbuild esbuild' and ensure the dependency is in package.json.

Warnings

gotcha Metro passes default uglify options to the minifier, including 'mangle', which is not valid for esbuild and causes 'Invalid option in transform() call: "mangle"' error. ↓

fix Reset transformer.minifierConfig to an object with only valid esbuild options in metro.config.js.

gotcha Using require.resolve('metro-minify-esbuild') is required; a string without resolve will not resolve correctly. ↓

fix Use require.resolve to get absolute path for minifierPath.

deprecated ESBuild options like 'minify', 'sourcemap' may conflict or be unnecessary since minifier only transforms; esbuild documentation recommends using only transform options. ↓

fix Refer to esbuild transform API for valid options.

Install

npm install metro-minify-esbuild

yarn add metro-minify-esbuild

pnpm add metro-minify-esbuild

Imports

metro-minify-esbuild
wrong
```
import minifier from 'metro-minify-esbuild'
```
correct
```
No direct import; configure via require.resolve in metro.config.js
```
This package is not imported directly. It's referenced via the minifierPath config option in metro.config.js.
transformer.minifierPath
wrong
```
transformer.minifierPath = 'metro-minify-esbuild'
```
correct
```
transformer.minifierPath = require.resolve('metro-minify-esbuild')
```
Must use require.resolve to get the absolute path; just passing the package name will fail.
transformer.minifierConfig
wrong
```
transformer.minifierConfig = {}
```
correct
```
transformer.minifierConfig = { /* esbuild options */ }
```
Metro passes default uglify options that break esbuild; reset to an object with only esbuild options.

Quickstart

Configure metro.config.js to use ESBuild minifier (CommonJS).

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// Use ESBuild as minifier
config.transformer.minifierPath = require.resolve('metro-minify-esbuild');

// Override default uglify options with esbuild options
config.transformer.minifierConfig = {
  // ESBuild transform options (optional)
  // e.g., target: 'es2015',
};

module.exports = config;