esbuild-jest-cli

4.0.4 verified Fri May 01 auth: no javascript

A CLI tool that bundles Jest test projects using esbuild for faster test execution. Current stable version is 4.0.4 (March 2025), with irregular releases. It supports Jest 27-29 and Node.js 14+. Differentiating features: automatic Jest config generation, esbuild plugin support, and optional dependency transformation. It can handle ESM and CJS, and includes metafile generation to produce jest.config.json. The tool is maintained by Wix Incubator and is suitable for projects seeking lightweight, efficient test bundling.

Common errors

error Cannot find module 'esbuild-jest-cli' ↓

cause Package not installed, or missing peer dependency esbuild.

fix

Run 'npm install --save-dev esbuild-jest-cli esbuild' and ensure node_modules is correct.

error TypeError: (0 , _esbuildJestCli.build) is not a function ↓

cause Using CommonJS require() on an ESM-only package.

fix

Change to dynamic import: const { build } = await import('esbuild-jest-cli'); or set type: module in package.json.

error Jest encountered an unexpected token. Use babel-jest or ts-jest ↓

cause esbuild-jest-cli did not transform the file correctly, possibly due to misconfiguration.

fix

Ensure Jest config uses esbuild-jest-cli's transformer or run via CLI with correct testPathPattern.

error Error: ESBUILD_BINARY_PATH environment variable is not set ↓

cause The internal esbuild binary path is missing (rare).

fix

Install esbuild globally or set ESBUILD_BINARY_PATH to the esbuild binary location.

Warnings

breaking v4.0.0 switched to optional dependencies and @swc/jest internally; preTransform/postTransform callbacks from v3.x are removed. ↓

fix Migrate to new transformer mechanism; remove any usage of preTransform/postTransform. See changelog for v3->v4 migration.

breaking v3.0.0 changed the transformer callback signatures (preTransform and postTransform). ↓

fix Update custom transformers to match the new API. See release notes.

gotcha The tool forces bundle: true, splitting: true, metafile: true, and sets outbase to cwd. Overriding these can cause breakage. ↓

fix Do not set bundle, splitting, metafile, or outbase in esbuild config — they are internally overridden.

deprecated Support for Node.js 14.x is deprecated and may be removed in a future major version. ↓

fix Upgrade Node.js to >=16.x.

gotcha The package is ESM-only; using require() directly may fail in older Node or CJS projects. ↓

fix Use dynamic import() or ensure your project is configured for ESM.

Install

npm install esbuild-jest-cli

yarn add esbuild-jest-cli

pnpm add esbuild-jest-cli

Imports

build
wrong
```
const { build } = require('esbuild-jest-cli')
```
correct
```
import { build } from 'esbuild-jest-cli'
```
Package is ESM-first; CJS require may fail depending on Node version and configuration.

default

wrong

const esbuildJestCli = require('esbuild-jest-cli')

correct

import esbuildJestCli from 'esbuild-jest-cli'

No default export exists (only named exports). The import will fail.

JestCliOptions

wrong

import { JestCliOptions } from 'esbuild-jest-cli'

correct

import type { JestCliOptions } from 'esbuild-jest-cli'

Type import only; not a runtime value.

Quickstart

Shows how to configure and run esbuild-jest-cli using a config file or programmatic API.

// In your project root, create .esbuild-jestrc.js:
module.exports = {
  esbuild: {
    outdir: '.bundle',
    sourcemap: true,
    platform: 'node'
  },
  package: {
    name: 'my-test-bundle'
  }
};

// Run the CLI:
// npx esbuild-jest --testPathPattern=.*.test.js

// Programmatic usage:
import { build } from 'esbuild-jest-cli';
await build({
  esbuild: {
    outdir: 'dist',
    sourcemap: true,
    external: ['chalk']
  },
  package: {
    name: 'custom-bundle'
  }
});
console.log('Tests bundled successfully!');