esbuild-esm-loader

0.3.3 verified Mon Apr 27 auth: no javascript

ESM loader for Node.js that transforms imports using ESBuild, supporting TypeScript, JSX, and modern JavaScript. Current stable version is 0.3.3 (major version zero, so minor versions may include breaking changes). Requires Node.js >=16.17.0 and ESBuild as a peer dependency. It uses Node.js module customization hooks (--import) for transparent transformation without a build step. Alternative to ts-node, tsx, or jiti; focuses purely on ESBuild integration.

Common errors

error Cannot find module 'esbuild' ↓

cause ESBuild peer dependency not installed.

fix

npm install esbuild

error Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported ↓

cause Trying to use require() on this ESM-only package.

fix

Use import syntax or switch to dynamic import.

error ExperimentalWarning: Customization hooks is an experimental feature ↓

cause Node.js warning when using loader hooks (always shown until hooks are stable).

fix

Suppress with --no-warnings, but ignore as non-critical.

Warnings

breaking In v0.x minor versions always include breaking changes. Expect breaking changes on minor bumps. ↓

fix Lock to patch version or pin with exact version.

deprecated Node --experimental-loader is deprecated; use --import instead. ↓

fix Use --import=esbuild-esm-loader/register instead of --experimental-loader.

gotcha Loader hooks are experimental in Node.js (still not stable as of Node 22). Integration with other loaders may break. ↓

fix Use only one ESM loader at a time unless chaining is supported.

gotcha ESBuild must be installed separately as a peer dependency. Missing esbuild causes runtime error. ↓

fix Run npm install esbuild alongside esbuild-esm-loader.

Install

npm install esbuild-esm-loader

yarn add esbuild-esm-loader

pnpm add esbuild-esm-loader

Imports

register

wrong

node -r esbuild-esm-loader/register ./entry.ts

correct

node --import=esbuild-esm-loader/register ./entry.ts

Use --import (ESM) not -r (CJS) for Node >=16.17.0

EsmLoader (default export)

wrong

const EsmLoader = require('esbuild-esm-loader')

correct

import EsmLoader from 'esbuild-esm-loader'

Package is ESM-only; CJS require will fail

load hook
```
import { load } from 'esbuild-esm-loader'
```
Named export for use in custom chain; available since v0.2.0

Quickstart

Shows how to use the loader via --import flag to transform TSX file on the fly with ESBuild.

// file: index.tsx
import React from 'react';
import { renderToStaticMarkup } from 'react-dom/server';

console.log(renderToStaticMarkup(<div>Hello World!</div>));
// Run: node --import=esbuild-esm-loader/register --enable-source-maps index.tsx