@ms-cloudpack/esm-stub-utilities

@ms-cloudpack/esm-stub-utilities

This library contains utilities for generating ESM stubs for CommonJS modules. Some bundlers require this for extracting named exports needed to produce a browser-compatible ESM bundle.

Usage

Generate a stub given a JavaScript entry path:

import { createESMStub } from '@ms-cloudpack/esm-stub-utilities';

const esmStub = await createESMStub('/path/to/entry.js', '/path/to/stub.js');

This return an esm stub string, based on loading the package in node and parsing exported keys. Example output:

import content from '/path/to/entry.js';

export {
  default: content,
  named1: content.named1,
  named2: content.named2
};

Writes the path to the stub to a file:

import { writeESMStub } from '@ms-cloudpack/esm-stub-utilities';

await writeESMStub('./path/to/entry.js', './path/to/stub.js');

Special considerations

When evaluating named entries in the exports of the cjs file, the library is loaded in the node process. A few libraries are used to simulate the browser environment in order for the script to load. (E.g. some libraries will reference window on load, and therefore must be parsed in an environment that accommodates this.)

Libraries which export a default entry in their exports will have that value preserved as the default export in the stub. However libraries which have an object exported which don't have a default key will have the entire object exported as the default.

Libraries which export a function or literal value as the exports result will have a default export for that entry.

Some libraries don't export anything. In this case, the stub will simply import the entry.

Exported members that are keywords will be ignored. (E.g. module.exports = { 'delete': "foo" }; would be considered an empty export.)