esbuild-runner

library2.2.2jsnpmunverified

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.

devops

npm install esbuild-runner

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-RUNNER

esbuild-runner

devopsjavascriptv2.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esr

✓ npx esr script.ts

Global binary; no import needed. Use npx or install globally.

esbuild-runner/register

✓ node -r esbuild-runner/register script.ts

✗ require('esbuild-runner/register')

Used as a Node.js require hook. Can also be used with --require or in code with require() at entry.

esbuild-runner/jest

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

✗ require('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.

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

esr --version

Debug

Known issues

gotchaesbuild-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

affects: >=2.0.0

gotchaIn 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

affects: >=1.0.0

deprecatedesbuild-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.

affects: <3.0.0

gotchaWhen 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.

affects: >=1.0.0

breakingIn 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.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild'

esbuild is a peer dependency and is not installed.

fix

npm install --save-dev esbuild

Error: require() of ES modules is not supported

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.

TypeError: tsconfig.json is not a valid configuration file

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.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; esbuild binary is used for all transpilation

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/folke/esbuild-runner ↗

packagehttps://www.npmjs.com/package/esbuild-runner ↗