{"id":11245,"library":"load-esm","title":"load-esm","description":"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.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/Borewit/load-esm","tags":["javascript","load-esm","ESM","Import ESM","CJS","CommonJS","TypeScript","Node.js","dynamic import","typescript"],"install":[{"cmd":"npm install load-esm","lang":"bash","label":"npm"},{"cmd":"yarn add load-esm","lang":"bash","label":"yarn"},{"cmd":"pnpm add load-esm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { loadEsm } = require('load-esm');","symbol":"loadEsm","correct":"import { loadEsm } from 'load-esm';"},{"note":"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.","symbol":"loadEsm (with typings)","correct":"await loadEsm<typeof import('my-esm-package')>('my-esm-package');"}],"quickstart":{"code":"import { loadEsm } from \"load-esm\";\n\n(async () => {\n  try {\n    // This example demonstrates loading the 'file-type' package, a pure ESM module.\n    // To run this, install 'file-type' (npm install file-type) and ensure\n    // 'fixture.gif' (or any valid file) exists in your project root.\n\n    // The generic type argument `typeof import(\"file-type\")` provides full type inference.\n    const { fileTypeFromFile } = await loadEsm<typeof import(\"file-type\")>(\n      \"file-type\"\n    );\n\n    const type = await fileTypeFromFile(\"fixture.gif\");\n    console.log(\"Detected file type:\", type); // e.g., { ext: 'gif', mime: 'image/gif' }\n  } catch (error) {\n    console.error(\"Error importing module or processing file:\", error);\n    // Common errors caught here include ERR_REQUIRE_ESM and ERR_PACKAGE_PATH_NOT_EXPORTED.\n  }\n})();","lang":"typescript","description":"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."},"warnings":[{"fix":"Rename all calls to `loadModule(...)` to `loadEsm(...)`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Wrap `loadEsm` calls within an `(async () => { ... })();` block or inside a named `async function`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update `loadEsm('pkg')` calls to `loadEsm<typeof import('pkg')>('pkg')` to leverage full type safety.","message":"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).","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `loadEsm('esm-module')` instead of `import('esm-module')` or `require('esm-module')` when in a CommonJS TypeScript project targeting pure ESM packages.","cause":"Attempting to `require()` a pure ECMAScript module from a CommonJS context, typically due to TypeScript transpilation changing `import()` to `require()`.","error":"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."},{"fix":"Import the package using `await loadEsm('package-name')` to correctly resolve its ESM entry points.","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.","error":"Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No \"exports\" main defined in package-name/package.json"},{"fix":"Provide a type argument to `loadEsm`: `await loadEsm<typeof import('my-esm-package')>('my-esm-package')`.","cause":"The dynamically loaded ESM module is not correctly typed, leading to `unknown` or `any` inference for its exports.","error":"Property 'someExport' does not exist on type 'unknown' (or 'any')."}],"ecosystem":"npm"}