{"id":30580376,"url":"https://github.com/borewit/load-esm","last_synced_at":"2025-10-18T17:50:30.272Z","repository":{"id":267263402,"uuid":"900702744","full_name":"Borewit/load-esm","owner":"Borewit","description":"Utility to dynamically load ESM modules in TypeScript CommonJS projects","archived":false,"fork":false,"pushed_at":"2025-02-28T10:19:44.000Z","size":23,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-21T00:05:55.787Z","etag":null,"topics":["cjs","commonjs","commonjs-modules","esm","esmodule","import","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Borewit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"Borewit","buy_me_a_coffee":"borewit"}},"created_at":"2024-12-09T10:11:15.000Z","updated_at":"2025-07-30T19:51:36.000Z","dependencies_parsed_at":"2024-12-09T11:27:33.319Z","dependency_job_id":"e4fd5696-ce1d-43d1-bbc8-61b9646b4fd2","html_url":"https://github.com/Borewit/load-esm","commit_stats":null,"previous_names":["borewit/esm-import"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Borewit/load-esm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Borewit%2Fload-esm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Borewit%2Fload-esm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Borewit%2Fload-esm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Borewit%2Fload-esm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Borewit","download_url":"https://codeload.github.com/Borewit/load-esm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Borewit%2Fload-esm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272634564,"owners_count":24967671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cjs","commonjs","commonjs-modules","esm","esmodule","import","typescript"],"created_at":"2025-08-29T05:23:27.834Z","updated_at":"2025-10-18T17:50:30.002Z","avatar_url":"https://github.com/Borewit.png","language":"TypeScript","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)\n[![NPM version](https://img.shields.io/npm/v/load-esm.svg)](https://npmjs.org/package/load-esm)\n[![npm downloads](http://img.shields.io/npm/dm/load-esm.svg)](https://npmcharts.com/compare/load-esm?start=365)\n\n# load-esm\n\n**load-esm** is a tiny utility that lets CommonJS (CJS) TypeScript projects **dynamically import pure ESM packages** at runtime—without hacks like `eval()`.\n\nIt helps avoid errors like:\n\n* `Error [ERR_REQUIRE_ESM]: require() of ES Module`\n* `Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No \"exports\" main defined in ...`\n\n---\n\n## Installation\n\n```bash\nnpm install load-esm\n# or\nyarn add load-esm\n# or\npnpm add load-esm\n```\n\n\u003e Works in CJS TypeScript projects. No config changes required.\n\n---\n\n## Quick start\n\n```ts\n// TypeScript (CJS project)\nimport { loadEsm } from \"load-esm\";\n\n(async () =\u003e {\n  const esmModule = await loadEsm(\"esm-module\");\n  // use esmModule...\n})();\n```\n\n### With typings\n\n```ts\nimport { loadEsm } from \"load-esm\";\n\n(async () =\u003e {\n  const esmModule = await loadEsm\u003ctypeof import(\"esm-module\")\u003e(\"esm-module\");\n  // esmModule is fully typed\n})();\n```\n\n### Concrete example (pure ESM package)\n\n```ts\nimport { loadEsm } from \"load-esm\";\n\n(async () =\u003e {\n  try {\n    // Import a pure ESM package from a CommonJS TS project\n    const { fileTypeFromFile } = await loadEsm\u003ctypeof import(\"file-type\")\u003e(\n      \"file-type\"\n    );\n\n    const type = await fileTypeFromFile(\"fixture.gif\");\n    console.log(type);\n  } catch (error) {\n    console.error(\"Error importing module:\", error);\n  }\n})();\n```\n\n\u003e Note: Because top‑level `await` isn’t available in CommonJS, examples use an async IIFE.\n\n---\n\n## API\n\n```ts\nfunction loadEsm\u003cT = unknown\u003e(name: string): Promise\u003cT\u003e\n```\n\n**Parameters**\n\n* `name` — Package name or file path to import.\n\n**Returns**\n\n* `Promise\u003cT\u003e` resolving to the imported module namespace.\n\n---\n\n## How it works\n\nIn CJS TypeScript projects (`\"module\": \"commonjs\"`), the TS compiler transpiles dynamic `import()` to `require()`, which **breaks** when the target is a pure ESM package.\n\n`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()`).\n\n### What about Node.js ≥ 22.12?\n\nSince 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:\n\n* You’re on older Node.js versions that support `import()` (see Compatibility) but not the newer `require()` behavior.\n* You want a single, consistent pattern that works across environments and avoids edge cases.\n\n\u003e If Node’s built‑in `require(esm)` works for your packages and version, feel free to use it.\n\n---\n\n## Compatibility\n\n* **Node.js**: ≥ 13.2.0 (first version with native `import()` support)\n* **TypeScript**: Fully typed; works in CJS projects.\n\n---\n\n## Troubleshooting\n\n* **`ERR_REQUIRE_ESM`**: Ensure you’re using `load-esm(...)` to import the ESM dependency from CJS code.\n* **`No \"exports\" main defined`**: Some packages only expose ESM entry points. Import them via `load-esm`.\n* **Type declarations**: Use the generic form `loadEsm\u003ctypeof import(\"pkg\")\u003e(\"pkg\")` for typed access.\n* **Top‑level await**: Wrap usage in an async IIFE in CJS.\n\n---\n\n## License\n\n[MIT](./LICENSE.txt)\n\n---\n\n### Changelog\n\nSee [Releases](https://github.com/Borewit/load-esm/releases).\n\n---\n\n### Acknowledgements\n\nInspired by common pain points when mixing CJS projects with modern ESM‑only libraries.\n","funding_links":["https://github.com/sponsors/Borewit","https://buymeacoffee.com/borewit"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborewit%2Fload-esm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborewit%2Fload-esm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborewit%2Fload-esm/lists"}