{"id":10808,"library":"esbuild-register","title":"esbuild-register","description":"esbuild-register is a utility that enables on-the-fly transpilation of JSX, TypeScript, and modern JavaScript (esnext) features in Node.js environments by leveraging the highly performant esbuild bundler. It functions as a Node.js `require` hook or an experimental `--loader`, allowing developers to execute TypeScript or JSX files directly without a prior build step. The current stable version is 3.6.0. While widely used, the package has a slow release cadence, with the last update two years ago, leading to it being classified as having 'not healthy' project activity by some analyses. Its primary differentiator compared to alternatives like `ts-node` or `babel-register` is its speed, attributed to `esbuild` being written in Go and optimized for fast compilation. It automatically respects `jsxFactory`, `jsxFragmentFactory`, and `target` options from `tsconfig.json`.","status":"maintenance","version":"3.6.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install esbuild-register","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-register","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-register","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core transpilation engine. Must be installed alongside esbuild-register as a peer dependency.","package":"esbuild","optional":false}],"imports":[{"note":"This is the primary way to use esbuild-register for CommonJS modules or when 'type': 'commonjs' in package.json. It hooks into Node.js's require system.","symbol":"CLI Runtime Hook","correct":"node -r esbuild-register file.ts"},{"note":"Required for projects with 'type': 'module' in package.json to correctly load TypeScript files as ES Modules. The `--loader` flag enables the experimental Node.js ESM loader.","wrong":"node -r esbuild-register ./file.ts (when 'type': 'module')","symbol":"ESM Loader","correct":"node --loader esbuild-register/loader -r esbuild-register ./file.ts"},{"note":"The programmatic API for `register` and `unregister` is exposed via a CommonJS module located at `dist/node`, hence `require` is the correct way to import it, even in an ESM context via a wrapper.","wrong":"import { register } from 'esbuild-register/dist/node'","symbol":"Programmatic Register","correct":"const { register } = require('esbuild-register/dist/node')"}],"quickstart":{"code":"/* file.ts */\nimport { createServer } from 'http';\n\ninterface Greeter {\n  greet(name: string): string;\n}\n\nconst myGreeter: Greeter = {\n  greet(name: string): string {\n    return `Hello, ${name}! This is esbuild-register running TypeScript.`;\n  },\n};\n\nconst server = createServer((req, res) => {\n  res.statusCode = 200;\n  res.setHeader('Content-Type', 'text/plain');\n  res.end(myGreeter.greet('World') + '\\n');\n});\n\nconst PORT = process.env.PORT ?? '3000';\nserver.listen(Number(PORT), () => {\n  console.log(`Server running at http://localhost:${PORT}/`);\n  console.log('Try running with: node -r esbuild-register file.ts');\n  console.log('Or for ESM projects: node --loader esbuild-register/loader -r esbuild-register file.ts');\n});\n","lang":"typescript","description":"Demonstrates running a simple TypeScript HTTP server using both the `require` hook and the experimental ESM loader."},"warnings":[{"fix":"As per discussions, the fix might involve updating Node.js or esbuild-register if a new version addresses this, or restructuring code to avoid the affected patterns. Users might need to downgrade Node.js or consider alternatives like `tsx` for robust ESM support.","message":"The experimental ESM loader (esbuild-register/loader) stopped working in Node.js 20.6.0 due to internal changes in Node.js's ESM loader implementation. This often manifested as 'SyntaxError: Cannot use import statement outside a module'. While potential fixes or workarounds might exist, relying on experimental Node.js features carries inherent risks of breakage in minor updates.","severity":"breaking","affected_versions":"Node.js >=20.6.0 (when using --loader)"},{"fix":"Carefully manage `esbuild` version pinned to the version `esbuild-register` was last tested with, or consult `esbuild-register`'s issues for compatibility notes with specific `esbuild` versions. Be prepared for potential breakage when updating `esbuild`.","message":"esbuild-register's peer dependency `esbuild` (current range `^0.12.0 <1`) is subject to frequent breaking changes in its own minor versions (e.g., esbuild v0.17 introduced breaking changes to `watch()`, `rebuild()`, and `serve()` APIs). While `esbuild-register` might generally work with newer `esbuild` versions within its peer dependency range, specific features or underlying API calls might break if esbuild-register has not been updated to accommodate `esbuild`'s breaking changes.","severity":"gotcha","affected_versions":">=3.0.0 (esbuild-register) with newer `esbuild` versions within the peer dependency range."},{"fix":"For performance-critical applications, consider a build step with `esbuild` directly, `tsc`, or a bundler like Webpack/Rollup with an esbuild loader, rather than relying solely on runtime transpilation.","message":"esbuild-register is a runtime transpiler, meaning it transpiles code on demand when Node.js encounters it. While significantly faster than other runtime transpilers, it still incurs overhead compared to a dedicated build step using `esbuild` directly as a bundler. For production deployments or large-scale applications, pre-compilation is generally recommended for optimal performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor Node.js release notes for updates on its loader API. For more stable ESM runtime execution, consider `tsx` which aims to provide a more robust experience, often by integrating similar loading mechanisms.","message":"The Node.js `--loader` flag used by `esbuild-register/loader` is still considered experimental by Node.js, even if `esbuild-register` exposes it. This means its behavior can change in future Node.js versions without adhering to semantic versioning, potentially leading to unexpected breakages.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ESM projects, use `node --loader esbuild-register/loader -r esbuild-register ./file.ts`. If on Node.js 20.6.0+, this error might indicate incompatibility due to Node.js's loader changes; consider a Node.js version downgrade or an alternative loader.","cause":"Using `node -r esbuild-register file.ts` in an ESM project (`\"type\": \"module\"` in package.json) or when Node.js's experimental loader behavior changed in 20.6.0.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Install `esbuild` explicitly: `npm install esbuild esbuild-register -D` (or `yarn add esbuild esbuild-register --dev`, `pnpm add esbuild esbuild-register -D`).","cause":"The peer dependency `esbuild` was not installed alongside `esbuild-register`.","error":"Error: Cannot find module 'esbuild'"},{"fix":"Use CommonJS `require` for programmatic access: `const { register } = require('esbuild-register/dist/node')`.","cause":"Attempting to `import { register } from 'esbuild-register/dist/node'` in an ESM context when the module is CJS-only or doesn't provide a named ESM export for `register`.","error":"TypeError: (0 , esbuild_register_dist_node_1.register) is not a function"}],"ecosystem":"npm"}