natemoo-re / require-or-import

Require or Import

Dynamically require CommonJS or import ECMAScript modules with consistent behavior.

Why?

Node officially supports both CommonJS (CJS) and ECMAScript modules (ESM)! Unfortunately, there inherent inconsistencies between the two formats, which can become difficult when loading a file of an unknown format.

This package attempts to smooth over those inconsistencies.

What does it do?

For authors of packages using native ECMAScript modules requireOrImport does not introduce any new behavior. It wraps import as a convenience.

For authors of packages using CommonJS modules requireOrImport uses either require or import according to Node's interoperability semantics. requireOrImport loads CommonJS modules as if they were loaded using import in an ECMAScript module environment.

Specifically, requireOrImport is an asynchronous function which always loads CommonJS modules as a namespace with a default export key pointing to the CommonJS module.exports value, as defined by Node's CommonJS Namespace behavior. Named exports are exposed using cjs-module-lexer.

Who should use this?

requireOrImport may be useful if you

• distribute both CommonJS and ECMAScript module entry points in your package
• distribute a compiled version of your sourcecode (although Node allows it, compilers tend to disallow mixed usage of require and import)
• need to load a file of an unknown format (like a user-supplied configuration file) and need that object to adhere to a consistent interface

Example

When loaded with requireOrImport(), the following files all return Promise<{ default: { test: 'abc' } }>.

// test.cjs
module.exports = { test: 'abc' };

// test.mjs
export default { test: 'abc' };

// test.js below `package.json` with `"type": "commonjs"`
module.exports = { test: 'abc' };

// test.js below `package.json` with `"type": "module"`
export default { test: 'abc' };

When loaded with requireOrImport(), the following files all return Promise<{ test: 'abc' }>.

// test.cjs
exports.test = 'abc';

// test.mjs
export const test = 'abc';

// test.js below `package.json` with `"type": "commonjs"`
exports.test: 'abc';

// test.js below `package.json` with `"type": "module"`
export const test = 'abc';