default-import

default-import

Properly handle CJS imports in ESM.

Contents

• Introduction
• Install
• Example
• Usage
• API
• Related Issues

Introduction

Handle importing unknown/CJS modules in ESM that do not properly export a default value.

Importing CJS is supported natively in ESM, and the "default" import is the raw module.exports value. See NodeJS docs.

Some libraries improperly mix "default" and "named" exports in CommonJS, which requires extra instrumenting that is not natively available in ESM.

This library intends to provide the most basic instrumentation to properly access the default import.

Install

npm i default-import

Example

// a.cts
export default 123;

export const named = 456;

Compiles to

// a.cjs
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.named = void 0;
exports.default = 123;
exports.named = 456;

So importing doesn't work as expected!

// b.ts
import a from './a.cjs';
import { defaultImport } from 'default-import';

console.log(a);
// Expected: 123
// Actual: { __esModule: true, default: 123, named: 456 }

console.log(defaultImport(a)) // 123

Usage

default-import is an ESM module. That means it must be imported. To load from a CJS module, use dynamic import const { defaultImport } = await import('default-import');.

defaultImport() is idempotent and handles properly exported defaults so it is safe to use in environments that correctly provide default imports. That said, it is generally overkill and unnecessary to use this library in those cases.

It is best used when the runtime/source is not entirely in control, such as NextJS (ESM on server, "commonjs" on browser).

API

defaultImport(*)

Extracts the proper default import from a CJS import.

Idempotent, and correctly handles proper default exports (e.g. default import from ESM .mjs file).

Related Issues

• NextJS
  • https://github.com/vercel/next.js/issues/30402
  • https://github.com/vercel/next.js/issues/32213
• Styled Components
  • https://github.com/styled-components/styled-components/issues/3437
  • https://github.com/styled-components/styled-components/issues/3601