load-esm

1.0.3 · active · verified Sun Apr 19

load-esm is a lightweight utility designed for TypeScript projects configured with CommonJS (`"module": "commonjs"`) that need to dynamically load pure ECMAScript Modules (ESM) at runtime. It directly addresses common interoperability errors such as `Error [ERR_REQUIRE_ESM]: require() of ES Module` and `Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in ...`. The utility functions by executing the native `import()` call outside of TypeScript's CommonJS transpilation scope, thereby preserving the correct dynamic import semantics at runtime. This approach provides a robust and type-safe solution without resorting to brittle workarounds like `eval()`. The current stable version is 1.0.3, with releases primarily focused on documentation improvements and ensuring compatibility with evolving Node.js and TypeScript ecosystems. Its key differentiator is providing a consistent, reliable mechanism for ESM-in-CJS loading across various Node.js versions, even beyond Node.js 22.12's `require()`-based ESM loading limitations.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module path/to/esm-module.js not supported. Instead change the require of path/to/esm-module.js to a dynamic import() which is available in all CommonJS modules.
```
cause Attempting to `require()` a pure ECMAScript module from a CommonJS context, typically due to TypeScript transpilation changing `import()` to `require()`.

fix Use `loadEsm('esm-module')` instead of `import('esm-module')` or `require('esm-module')` when in a CommonJS TypeScript project targeting pure ESM packages.
```
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in package-name/package.json
```
cause Attempting to access a module path that is not explicitly exposed via the 'exports' field in the target package's `package.json`, common for ESM-only packages not designed for direct `require()` access.

fix Import the package using `await loadEsm('package-name')` to correctly resolve its ESM entry points.
```
Property 'someExport' does not exist on type 'unknown' (or 'any').
```
cause The dynamically loaded ESM module is not correctly typed, leading to `unknown` or `any` inference for its exports.

fix Provide a type argument to `loadEsm`: `await loadEsm<typeof import('my-esm-package')>('my-esm-package')`.

Warnings

breaking The primary function name was changed from `loadModule()` to `loadEsm()` in version 1.0.0. Projects upgrading from pre-1.0.0 versions must update their calls.
Fix: Rename all calls to `loadModule(...)` to `loadEsm(...)`.
gotcha Top-level `await` is not available in CommonJS modules. When using `loadEsm` in a CJS context, you must wrap the asynchronous operation in an async IIFE (Immediately Invoked Function Expression) or an async function.
Fix: Wrap `loadEsm` calls within an `(async () => { ... })();` block or inside a named `async function`.
gotcha While Node.js versions 22.12+ offer some `require()`-based ESM loading capabilities, these come with documented constraints. `load-esm` provides a consistent and often more reliable method across various Node.js versions and complex ESM package structures.
Fix: Evaluate if Node.js's built-in `require(esm)` fully meets your needs, otherwise, `load-esm` offers a more robust solution for dynamic imports.
gotcha When loading ESM packages, ensure you provide the correct generic type argument `typeof import('package-name')` to `loadEsm` for accurate TypeScript inference. Omitting this will result in the imported module being typed as `unknown` (or `any` in older TS configurations).
Fix: Update `loadEsm('pkg')` calls to `loadEsm<typeof import('pkg')>('pkg')` to leverage full type safety.

Install

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

Imports

loadEsm
wrong:
```
const { loadEsm } = require('load-esm');
```
correct:
```
import { loadEsm } from 'load-esm';
```
This utility is specifically designed to be imported as an ES module within a CommonJS TypeScript project. Using `require()` for `load-esm` itself will not leverage its core functionality designed for dynamic ESM loading.
loadEsm (with typings)
```
await loadEsm<typeof import('my-esm-package')>('my-esm-package');
```
For full type inference and safety in TypeScript, always provide the generic type argument `typeof import('module-name')`. This correctly types the dynamically loaded module's namespace.

Quickstart

Demonstrates how to dynamically import a pure ESM package (e.g., 'file-type') within a CommonJS TypeScript project, utilizing `loadEsm` with proper TypeScript generic typings for full inference.

import { loadEsm } from "load-esm";

(async () => {
  try {
    // This example demonstrates loading the 'file-type' package, a pure ESM module.
    // To run this, install 'file-type' (npm install file-type) and ensure
    // 'fixture.gif' (or any valid file) exists in your project root.

    // The generic type argument `typeof import("file-type")` provides full type inference.
    const { fileTypeFromFile } = await loadEsm<typeof import("file-type")>(
      "file-type"
    );

    const type = await fileTypeFromFile("fixture.gif");
    console.log("Detected file type:", type); // e.g., { ext: 'gif', mime: 'image/gif' }
  } catch (error) {
    console.error("Error importing module or processing file:", error);
    // Common errors caught here include ERR_REQUIRE_ESM and ERR_PACKAGE_PATH_NOT_EXPORTED.
  }
})();

view raw JSON →