load-esm

library1.0.3jsnpmunverified

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.

http-networking

npm install load-esm

github ↗package ↗

INSTALL

IMPORT

SIG · LOAD-ESM

load-esm

http-networkingjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loadEsm

✓ import { loadEsm } from 'load-esm';

✗ const { loadEsm } = require('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.

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. } })();

Debug

Known issues

breakingThe 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(...)`.

affects: >=1.0.0

gotchaTop-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`.

affects: >=0.1.0

gotchaWhile 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.

affects: >=0.1.0

gotchaWhen 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.

affects: >=0.1.0

Errors

Common errors & fixes

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.

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

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').

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')`.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Borewit/load-esm ↗

packagehttps://www.npmjs.com/package/load-esm ↗