{"id":25444,"library":"esbuild-runner-plugins","title":"esbuild-runner (esr)","description":"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.","status":"active","version":"2.3.0-plugins.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/bashmish/esbuild-runner","tags":["javascript","esbuild","typescript","commonjs","jest","esnext","cjs","node","nodejs"],"install":[{"cmd":"npm install esbuild-runner-plugins","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-runner-plugins","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-runner-plugins","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core transpilation engine.","package":"esbuild","optional":false}],"imports":[{"note":"esr is a CLI binary; import is not applicable. Use npx or globally install.","wrong":"esr script.ts (if not installed globally)","symbol":"esr","correct":"npx esr script.ts"},{"note":"CommonJS only; no ESM equivalent. Use with node -r or runtime require.","wrong":"import 'esbuild-runner/register'","symbol":"register","correct":"require('esbuild-runner/register')"},{"note":"Must specify /jest subpath in Jest config.","wrong":"transform: { '\\.ts$': 'esbuild-runner' }","symbol":"jest transform","correct":"transform: { '\\.ts$': 'esbuild-runner/jest' }"},{"note":"Config file uses CommonJS, not ES modules.","wrong":"export default { ... }","symbol":"esbuild runner config","correct":"module.exports = { type: 'transform', esbuild: { target: 'esnext' } }"}],"quickstart":{"code":"// Install locally\nnpm add --dev esbuild-runner esbuild\n\n// Create a TypeScript file: hello.ts\nexport function greet(name: string): string {\n  return `Hello, ${name}!`;\n}\n\n// Run it with esr (no build step)\nesr -e 'console.log(greet(\"World\"))' hello.ts\n\n// Or use register for REPL or scripts\nnode -r esbuild-runner/register -e \"const { greet } = require('./hello'); console.log(greet('World'));\"","lang":"typescript","description":"Shows CLI and programmatic usage with TypeScript, including esr binary and require hook."},"warnings":[{"fix":"Configure esbuild options in esbuild-runner.config.js to adjust target or include specific modules.","message":"esbuild-runner does not transpile node_modules by default; if a dependency uses unsupported JS features, it may fail at runtime.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use standard esbuild-runner (non-plugins) unless you specifically need compatibility with esbuild plugins.","message":"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.","severity":"gotcha","affected_versions":"2.3.0-plugins.0"},{"fix":"Use bundle mode (default) for best performance; avoid relying on transform cache.","message":"The --cache flag is not stable and may be removed in future versions.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use esbuild's supported syntax or consider alternative runners like tsx.","message":"esbuild-runner does not support all Node.js features; notably, 'import()' with CJS modules may not work as expected.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"npm install --save-dev esbuild-runner","cause":"Package not installed or installed incorrectly.","error":"Error: Cannot find module 'esbuild-runner/register'"},{"fix":"npm install --save-dev esbuild","cause":"Missing esbuild peer dependency.","error":"TypeError: esbuild is not a function"},{"fix":"Use require() instead of import, or use -r flag with node.","cause":"Trying to require an ESM-only package; register is CJS only.","error":"Error: Must use import to load ES Module: esbuild-runner/register"},{"fix":"Run with -r esbuild-runner/register or use esr binary.","cause":"esbuild-runner not registered or misconfigured.","error":"SyntaxError: Unexpected token 'export'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}