module-compat

Module type detection and loading for CJS and ESM compatibility.

Installation

npm install module-compat

API

Type Detection

import { moduleType, extToModuleType } from 'module-compat';

// Detect from file path (checks extension + package.json)
moduleType('/path/to/file.js'); // 'module' | 'commonjs'

// Detect from extension only (no filesystem access)
extToModuleType('.mjs'); // 'module'
extToModuleType('.cjs'); // 'commonjs'
extToModuleType('.js');  // undefined (need package.json check)

Capability Detection

import { supportsESM, supportsSyncRequireESM } from 'module-compat';

supportsESM();           // true if Node 12+
supportsSyncRequireESM(); // true if Node 23+

Module Loading

import { loadModule, loadModuleSync } from 'module-compat';

// Callback-based (CJS on all Node versions; ESM on Node 12+ through the ESM import entry)
loadModule('/path/to/module.mjs', (err, mod) => {
  if (err) throw err;
  console.log(mod);
});

// With options
loadModule('/path/to/module.mjs', { interop: 'raw' }, (err, mod) => {
  // mod is the full namespace: { default, namedExport1, ... }
});

// Sync (CJS always works, ESM requires Node 23+)
const mod = loadModuleSync('/path/to/module.cjs');

Interop Modes

Control how ESM default exports are handled:

| Mode | Behavior | |------|----------| | 'default' | Extract .default if present (default) | | 'raw' | Return module namespace as-is | | 'typescript' | Check __esModule flag, then extract default |

// ESM module: export default fn; export function helper() {}

// interop: 'default' (default)
loadModule('module.mjs', (err, mod) => {
  // mod = fn (the default export)
});

// interop: 'raw'
loadModule('module.mjs', { interop: 'raw' }, (err, mod) => {
  // mod = { default: fn, helper: [Function] }
});

Node Version Support

| Node Version | CJS files | ESM async via ESM import | ESM async via CJS require | ESM sync | |-------------|-----------|-------------------------|-------------------------|----------| | < 12 | Yes | No | No | No | | 12-22 | Yes | Yes | No | No | | 23+ | Yes | Yes | Yes | Yes |

For ESM files on Node 12-22, import module-compat through its ESM entry. The CommonJS entry cannot load ESM files on those versions because its dynamic import is transpiled to require(). CommonJS consumers need Node 23+ for ESM loading. supportsESM() reports whether the runtime supports ESM at all.