{"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,"search_vec":"'/register':74 '2.2.2':24 'binari':63 'bundl':52 'cach':59 'cjs':92 'commonj':89 'compil':49 'current':20 'default':54 'depend':85 'design':25 'drop':29 'drop-in':28 'esbuild':2,19,44,72,81,87 'esbuild-runn':1,71 'esnext':91 'esr':4,64 'fast':6 'faster':38 'fli':10 'hook':69 'instead':45 'javascript':86 'jest':78,90 'js':14 'jsx':17 'leverag':43 'mode':53,57 'modern':13 'node':35,93 'node.js':67 'nodej':94 'on-the-fli':7 'peer':84 'r':70 'replac':31 'requir':68,80 'runner':3,73 'signific':37 'stabl':21 'startup':39 'support':50 'transform':56,79 'transpil':11,41 'ts':34 'ts-node':33 'typescript':15,48,88 'use':18 'version':22 'work':60","created_at":"2026-04-27T16:59:06.695590+00:00","updated_at":"2026-04-27T16:59:06.695590+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"esr","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/folke/esbuild-runner","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/esbuild-runner","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-18","next_check":"2026-07-26","install_tag":null}}