craco-esbuild

0.6.1 verified Mon Apr 27 auth: no javascript

craco-esbuild is a CRACO plugin that replaces Babel and Terser in Create React App with esbuild for significantly faster compilation, development, and test runs. Version 0.6.1 is stable but sees infrequent releases. It swaps babel-loader for esbuild-loader, TerserPlugin for ESBuildMinifyPlugin, and optionally OptimizeCssAssetsWebpackPlugin for esbuild's CSS minifier. Jest tests can use esbuild-jest instead of babel-jest. Requires @craco/craco ^7.0.0 and react-scripts ^5.0.0. Unlike alternatives like react-app-rewired or custom CRA forks, craco-esbuild integrates via CRACO's plugin system and does not require ejecting or maintaining a separate Webpack config.

Common errors

error Module not found: Error: Can't resolve 'esbuild' in '...' ↓

cause esbuild is not installed as a dependency. craco-esbuild does not automatically install esbuild.

fix

Install esbuild: npm install --save-dev esbuild

error ValidationError: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause CRACO plugin configuration is incorrect, often due to missing or misspelled options.

fix

Check craco.config.js: ensure plugin object has { plugin: CracoEsbuildPlugin } and options are properly structured (e.g., esbuildLoaderOptions, not esbuildLoader).

error TypeError: CracoEsbuildPlugin is not a constructor ↓

cause Using an incorrect import style (e.g., default import via ES module) when the package is CommonJS.

fix

Use require('craco-esbuild') instead of import. In craco.config.js, const CracoEsbuildPlugin = require('craco-esbuild');

error UnhandledPromiseRejectionWarning: Error: No known conditions for './package.json' specifier in 'esbuild' package ↓

cause Version mismatch between craco-esbuild and esbuild. esbuild >=0.8.0 changed module resolution.

fix

Install a compatible esbuild version: npm install esbuild@0.7.22 or check craco-esbuild peerDependencies.

Warnings

breaking craco-esbuild may not work with react-scripts versions other than 5.x. Using older react-scripts (e.g., 4.x) will cause webpack configuration conflicts. ↓

fix Ensure react-scripts is version 5.x. Check compatibility with @craco/craco version (requires ^7.0.0).

breaking If your project uses TypeScript, you must configure esbuildLoaderOptions with loader: 'tsx' in craco.config.js. Missing this results in build failures because esbuild defaults to JSX loader. ↓

fix In craco.config.js, set esbuildLoaderOptions: { loader: 'tsx' }.

gotcha CracoEsbuildPlugin replaces babel-loader for all files, including those that might need Babel plugins (e.g., for polyfills or custom transforms). esbuild does not support Babel plugins. ↓

fix If you rely on Babel plugins (e.g., import/export, class properties), consider using esbuild's built-in transforms or replace the plugin with a custom solution that combines esbuild and Babel.

gotcha When skipEsbuildJest is false (default), esbuild-jest replaces babel-jest for test files. This may cause issues with test files that use JSX or TypeScript without proper loader configuration. ↓

fix Set skipEsbuildJest: true in plugin options to revert to babel-jest for tests, or configure esbuildJestOptions with appropriate loaders.

Install

npm install craco-esbuild

yarn add craco-esbuild

pnpm add craco-esbuild

Imports

CracoEsbuildPlugin
wrong
```
import CracoEsbuildPlugin from 'craco-esbuild';
```
correct
```
const CracoEsbuildPlugin = require('craco-esbuild');
```
craco-esbuild is a CommonJS package; ESM import may cause errors. Use require() in craco.config.js which is typically not transpiled.

Quickstart

Install craco-esbuild with @craco/craco, configure the plugin in craco.config.js, and update scripts to use craco instead of react-scripts.

// 1. Install: npm install --save-dev @craco/craco craco-esbuild
// 2. Create craco.config.js:
const CracoEsbuildPlugin = require('craco-esbuild');

module.exports = {
  plugins: [{ plugin: CracoEsbuildPlugin }],
};

// 3. Update package.json scripts:
{
  "scripts": {
    "start": "craco start",
    "build": "craco build",
    "test": "craco test"
  }
}

// 4. Run: npm start