esbuild-runner (esr)

2.2.2 verified Mon Apr 27 auth: no javascript

A fast on-the-fly transpiler for modern JS, TypeScript, and JSX using esbuild. Current stable version is 2.2.2. Designed as a drop-in replacement for ts-node with significantly faster startup and transpilation by leveraging esbuild instead of the TypeScript compiler. Supports both bundle mode (default) and transform mode with caching. Works as a binary (esr), as a Node.js require hook (-r esbuild-runner/register), and as a Jest transformer. Requires esbuild as a peer dependency.

Common errors

error Error: Cannot find module 'esbuild' ↓

cause esbuild is a peer dependency and is not installed.

fix

npm install --save-dev esbuild

error Error: require() of ES modules is not supported ↓

cause esbuild-runner does not support ES module syntax in the entry file by default.

fix

Use CommonJS syntax or ensure your file is compiled to CommonJS before using esr.

error TypeError: tsconfig.json is not a valid configuration file ↓

cause esbuild-runner does not read tsconfig.json automatically. esbuild options must be set in esbuild-runner.config.js.

fix

Create esbuild-runner.config.js and set esbuild options like target, loader, etc.

Warnings

gotcha esbuild-runner requires esbuild as a peer dependency. If not installed, you'll get an error when running esr. ↓

fix Install esbuild: npm install --save-dev esbuild

gotcha In bundle mode (default), dependencies from package.json or node_modules are never transpiled. If you rely on runtime transpilation of dependencies, use --cache (transform mode). ↓

fix Use transform mode: esr --cache script.ts

deprecated esbuild-runner's transform mode caching may not clear automatically if source files change outside of the cache. Use --clearCache to force clear. ↓

fix Run esr --clearCache before starting fresh runs, or delete the cache directory manually.

gotcha When using the require hook (esbuild-runner/register), the hook is installed globally and may affect other requires in the process. Use with caution in production. ↓

fix Only use the require hook in development or for specific scripts.

breaking In version 2.x, the CLI binary changed from 'esr' to 'esr' (same). But some scripts may rely on the old 'esbuild-runner' path. ↓

fix Use npx esr or add esr to PATH.

Install

npm install esbuild-runner

yarn add esbuild-runner

pnpm add esbuild-runner

Imports

esr
```
npx esr script.ts
```
Global binary; no import needed. Use npx or install globally.
esbuild-runner/register
wrong
```
require('esbuild-runner/register')
```
correct
```
node -r esbuild-runner/register script.ts
```
Used as a Node.js require hook. Can also be used with --require or in code with require() at entry.
esbuild-runner/jest
wrong
```
require('esbuild-runner/jest')
```
correct
```
transform: { '\\.ts$': 'esbuild-runner/jest' }
```
Jest transformer; configured in jest.config.js transform object.
esbuild-runner.config.js
```
module.exports = { type: 'bundle', esbuild: { target: 'esnext' } }
```
Configuration file placed in project root, not imported directly.

Quickstart

Create a simple TypeScript file and run it with esr binary, or configure Jest to use esbuild-runner for transforming TypeScript.

// hello-world.ts
const greeting: string = 'Hello, esbuild-runner!';
console.log(greeting);

// Run: npx esr hello-world.ts
// Or with jest:
// jest.config.js
// module.exports = { transform: { '\\.ts$': 'esbuild-runner/jest' } }
// Then run: npx jest