esbuild-runner (esr)

2.3.0-plugins.0 verified Fri May 01 auth: no javascript

esbuild-runner (esr) is a high-speed on-the-fly transpiler for modern JavaScript, TypeScript, and JSX, powered by esbuild. It replaces slower alternatives like ts-node and babel-register for running scripts, tests, or arbitrary code without pre-building. Current version is 2.3.0-plugins.0, built on esbuild (peer dependency of any version). It offers two modes: bundling (default, one-shot esbuild invocation) and transform (file-by-file with caching via --cache flag). Useful for development workflows, Jest transforms, and VSCode debugging. Ships TypeScript definitions. No built-in plugins; the 'plugins' suffix indicates compatibility with esbuild plugins.

Common errors

error Error: Cannot find module 'esbuild-runner/register' ↓

cause Package not installed or installed incorrectly.

fix

npm install --save-dev esbuild-runner

error TypeError: esbuild is not a function ↓

cause Missing esbuild peer dependency.

fix

npm install --save-dev esbuild

error Error: Must use import to load ES Module: esbuild-runner/register ↓

cause Trying to require an ESM-only package; register is CJS only.

fix

Use require() instead of import, or use -r flag with node.

error SyntaxError: Unexpected token 'export' ↓

cause esbuild-runner not registered or misconfigured.

fix

Run with -r esbuild-runner/register or use esr binary.

Warnings

gotcha esbuild-runner does not transpile node_modules by default; if a dependency uses unsupported JS features, it may fail at runtime. ↓

fix Configure esbuild options in esbuild-runner.config.js to adjust target or include specific modules.

gotcha The 'plugins' version suffix (e.g., 2.3.0-plugins.0) may cause confusion with regular esbuild-runner; plugins are not included, only the runner. ↓

fix Use standard esbuild-runner (non-plugins) unless you specifically need compatibility with esbuild plugins.

deprecated The --cache flag is not stable and may be removed in future versions. ↓

fix Use bundle mode (default) for best performance; avoid relying on transform cache.

gotcha esbuild-runner does not support all Node.js features; notably, 'import()' with CJS modules may not work as expected. ↓

fix Use esbuild's supported syntax or consider alternative runners like tsx.

Install

npm install esbuild-runner-plugins

yarn add esbuild-runner-plugins

pnpm add esbuild-runner-plugins

Imports

esr
wrong
```
esr script.ts (if not installed globally)
```
correct
```
npx esr script.ts
```
esr is a CLI binary; import is not applicable. Use npx or globally install.
register
wrong
```
import 'esbuild-runner/register'
```
correct
```
require('esbuild-runner/register')
```
CommonJS only; no ESM equivalent. Use with node -r or runtime require.

jest transform

wrong

transform: { '\.ts$': 'esbuild-runner' }

correct

transform: { '\.ts$': 'esbuild-runner/jest' }

Must specify /jest subpath in Jest config.

esbuild runner config

wrong

export default { ... }

correct

module.exports = { type: 'transform', esbuild: { target: 'esnext' } }

Config file uses CommonJS, not ES modules.

Quickstart

Shows CLI and programmatic usage with TypeScript, including esr binary and require hook.

// Install locally
npm add --dev esbuild-runner esbuild

// Create a TypeScript file: hello.ts
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

// Run it with esr (no build step)
esr -e 'console.log(greet("World"))' hello.ts

// Or use register for REPL or scripts
node -r esbuild-runner/register -e "const { greet } = require('./hello'); console.log(greet('World'));"