{"id":21289,"library":"esbuild-runner","title":"esbuild-runner (esr)","description":"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.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/folke/esbuild-runner","tags":["javascript","esbuild","typescript","commonjs","jest","esnext","cjs","node","nodejs"],"install":[{"cmd":"npm install esbuild-runner","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-runner","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-runner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; esbuild binary is used for all transpilation","package":"esbuild","optional":false}],"imports":[{"note":"Global binary; no import needed. Use npx or install globally.","wrong":"","symbol":"esr","correct":"npx esr script.ts"},{"note":"Used as a Node.js require hook. Can also be used with --require or in code with require() at entry.","wrong":"require('esbuild-runner/register')","symbol":"esbuild-runner/register","correct":"node -r esbuild-runner/register script.ts"},{"note":"Jest transformer; configured in jest.config.js transform object.","wrong":"require('esbuild-runner/jest')","symbol":"esbuild-runner/jest","correct":"transform: { '\\\\.ts$': 'esbuild-runner/jest' }"},{"note":"Configuration file placed in project root, not imported directly.","wrong":"","symbol":"esbuild-runner.config.js","correct":"module.exports = { type: 'bundle', esbuild: { target: 'esnext' } }"}],"quickstart":{"code":"// hello-world.ts\nconst greeting: string = 'Hello, esbuild-runner!';\nconsole.log(greeting);\n\n// Run: npx esr hello-world.ts\n// Or with jest:\n// jest.config.js\n// module.exports = { transform: { '\\\\.ts$': 'esbuild-runner/jest' } }\n// Then run: npx jest","lang":"typescript","description":"Create a simple TypeScript file and run it with esr binary, or configure Jest to use esbuild-runner for transforming TypeScript."},"warnings":[{"fix":"Install esbuild: npm install --save-dev esbuild","message":"esbuild-runner requires esbuild as a peer dependency. If not installed, you'll get an error when running esr.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use transform mode: esr --cache script.ts","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run esr --clearCache before starting fresh runs, or delete the cache directory manually.","message":"esbuild-runner's transform mode caching may not clear automatically if source files change outside of the cache. Use --clearCache to force clear.","severity":"deprecated","affected_versions":"<3.0.0"},{"fix":"Only use the require hook in development or for specific scripts.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use npx esr or add esr to PATH.","message":"In version 2.x, the CLI binary changed from 'esr' to 'esr' (same). But some scripts may rely on the old 'esbuild-runner' path.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install --save-dev esbuild","cause":"esbuild is a peer dependency and is not installed.","error":"Error: Cannot find module 'esbuild'"},{"fix":"Use CommonJS syntax or ensure your file is compiled to CommonJS before using esr.","cause":"esbuild-runner does not support ES module syntax in the entry file by default.","error":"Error: require() of ES modules is not supported"},{"fix":"Create esbuild-runner.config.js and set esbuild options like target, loader, etc.","cause":"esbuild-runner does not read tsconfig.json automatically. esbuild options must be set in esbuild-runner.config.js.","error":"TypeError: tsconfig.json is not a valid configuration file"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}