# module-compat

> Module type detection and loading for CJS and ESM compatibility

Latest version **0.1.3** (published 2026-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install module-compat
pnpm add module-compat
yarn add module-compat
bun add module-compat
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2026-09-12 |
| First published | 2025-12-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=0.8 |
| Dependencies | 1 |
| Unpacked size | 57.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Kevin Malakoff |
| Maintainers | kmalakoff |
| Keywords | module, esm, cjs, commonjs, import, require, compatibility, loader |

## Links

- npm: https://www.npmjs.com/package/module-compat
- Repository: https://github.com/kmalakoff/module-compat
- Issues: https://github.com/kmalakoff/module-compat/issues
- npm.io page: https://npm.io/package/module-compat

## Dependencies (1)

- [module-root-sync](https://npm.io/package/module-root-sync.md) *

## Recent versions

- 0.1.3 (latest) — 2026-09-12
- 0.1.2 — 2026-08-24
- 0.1.1 — 2025-12-19
- 0.1.0 — 2025-12-19

## README

# module-compat

Module type detection and loading for CJS and ESM compatibility.

## Installation

```bash
npm install module-compat
```

## API

### Type Detection

```typescript
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

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

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

### Module Loading

```typescript
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 |

```typescript
// 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.

---
_Source: https://npm.io/package/module-compat · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._