# load-esm > Utility to dynamically load ESM modules in TypeScript CommonJS projects Latest version **1.0.3** (published 2025-08-24) · MIT license · 0 weekly downloads ## Install ```sh npm install load-esm pnpm add load-esm yarn add load-esm bun add load-esm ``` ## Health **Score 45/100 (D)** — status: stable. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 1.0.3 | | Published | 2025-08-24 | | First published | 2024-12-09 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=13.2.0 | | Dependencies | 0 | | Unpacked size | 6.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 40 | | Author | Borewit | | Maintainers | borewit | | Keywords | load-esm, ESM, Import ESM, CJS, CommonJS, TypeScript, Node.js, dynamic import, dynamic module loading, dynamic load, JavaScript modules, CJS ESM interoperability, import ESM in CommonJS, typescript commonjs import esm, module interoperability, node esm loader, mixed module, dynamic esm import typescript, cjs to esm bridge, ERR_REQUIRE_ESM, require ESM error, ERR_PACKAGE_PATH_NOT_EXPORTED, No "exports" main defined in, exports not defined error | ## Links - npm: https://www.npmjs.com/package/load-esm - Repository: https://github.com/Borewit/load-esm - Homepage: https://github.com/Borewit/load-esm#readme - Issues: https://github.com/Borewit/load-esm/issues - Funding: https://github.com/sponsors/Borewit - npm.io page: https://npm.io/package/load-esm ## Alternatives - [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads - [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads - [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads - [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads - [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads ## Recent versions - 1.0.3 (latest) — 2025-08-24 - 1.0.2 — 2025-02-28 - 1.0.1 — 2024-12-18 - 1.0.0 — 2024-12-13 - 0.1.1 — 2024-12-11 - 0.1.0 — 2024-12-09 ## README [![Node.js CI](https://github.com/Borewit/load-esm/actions/workflows/nodejs-ci.yml/badge.svg)](https://github.com/Borewit/load-esm/actions/workflows/nodejs-ci.yml) [![NPM version](https://img.shields.io/npm/v/load-esm.svg)](https://npmjs.org/package/load-esm) [![npm downloads](http://img.shields.io/npm/dm/load-esm.svg)](https://npmcharts.com/compare/load-esm?start=365) # 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 ```bash 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 ```ts // TypeScript (CJS project) import { loadEsm } from "load-esm"; (async () => { const esmModule = await loadEsm("esm-module"); // use esmModule... })(); ``` ### With typings ```ts import { loadEsm } from "load-esm"; (async () => { const esmModule = await loadEsm("esm-module"); // esmModule is fully typed })(); ``` ### Concrete example (pure ESM package) ```ts import { loadEsm } from "load-esm"; (async () => { try { // Import a pure ESM package from a CommonJS TS project const { fileTypeFromFile } = await loadEsm( "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 ```ts function loadEsm(name: string): Promise ``` **Parameters** * `name` — Package name or file path to import. **Returns** * `Promise` 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](https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require). 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("pkg")` for typed access. * **Top‑level await**: Wrap usage in an async IIFE in CJS. --- ## License [MIT](./LICENSE.txt) --- ### Changelog See [Releases](https://github.com/Borewit/load-esm/releases). --- ### Acknowledgements Inspired by common pain points when mixing CJS projects with modern ESM‑only libraries. --- _Source: https://npm.io/package/load-esm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._