load-esm

load-esm

load-esm is a tiny utility that lets CommonJS (CJS) TypeScript projects dynamically import pure ESM packages at runtime—without hacks like eval().

It helps avoid errors like:

• Error [ERR_REQUIRE_ESM]: require() of ES Module
• Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in ...

Installation

npm install load-esm
# or
yarn add load-esm
# or
pnpm add load-esm

Works in CJS TypeScript projects. No config changes required.

Quick start

// TypeScript (CJS project)
import { loadEsm } from "load-esm";

(async () => {
  const esmModule = await loadEsm("esm-module");
  // use esmModule...
})();

With typings

import { loadEsm } from "load-esm";

(async () => {
  const esmModule = await loadEsm<typeof import("esm-module")>("esm-module");
  // esmModule is fully typed
})();

Concrete example (pure ESM package)

import { loadEsm } from "load-esm";

(async () => {
  try {
    // Import a pure ESM package from a CommonJS TS project
    const { fileTypeFromFile } = await loadEsm<typeof import("file-type")>(
      "file-type"
    );

    const type = await fileTypeFromFile("fixture.gif");
    console.log(type);
  } catch (error) {
    console.error("Error importing module:", error);
  }
})();

Note: Because top‑level await isn’t available in CommonJS, examples use an async IIFE.

API

function loadEsm<T = unknown>(name: string): Promise<T>

Parameters

• name — Package name or file path to import.

Returns

• Promise<T> resolving to the imported module namespace.

How it works

In CJS TypeScript projects ("module": "commonjs"), the TS compiler transpiles dynamic import() to require(), which breaks when the target is a pure ESM package.

load-esm executes the import() outside of TypeScript’s transpilation scope, preserving native dynamic import() semantics at runtime. This keeps your code type‑safe while avoiding brittle workarounds (e.g., wrapping import() in eval()).

What about Node.js ≥ 22.12?

Since Node.js 22.12, require can load some ESM modules, but there are documented constraints. If your dependencies are compatible with that path, you might not need this utility. load-esm remains useful when:

• You’re on older Node.js versions that support import() (see Compatibility) but not the newer require() behavior.
• You want a single, consistent pattern that works across environments and avoids edge cases.

If Node’s built‑in require(esm) works for your packages and version, feel free to use it.

Compatibility

• Node.js: ≥ 13.2.0 (first version with native import() support)
• TypeScript: Fully typed; works in CJS projects.

Troubleshooting

• ERR_REQUIRE_ESM: Ensure you’re using load-esm(...) to import the ESM dependency from CJS code.
• No "exports" main defined: Some packages only expose ESM entry points. Import them via load-esm.
• Type declarations: Use the generic form loadEsm<typeof import("pkg")>("pkg") for typed access.
• Top‑level await: Wrap usage in an async IIFE in CJS.

License

MIT

Changelog

See Releases.

Acknowledgements

Inspired by common pain points when mixing CJS projects with modern ESM‑only libraries.