/cjs-loader

Node.js loader for compiling ESM & TypeScript modules to CommonJS

Primary LanguageTypeScriptMIT LicenseMIT

cjs-loader

Node.js require() hook to instantaneously transform ESM & TypeScript to CommonJS on demand using esbuild.

Features

  • Transforms ESM & TypeScript to CommonJS on demand
  • Supports TS extensions .cjs & .mjs (.cts & .mts)
  • Cached for performance boost
  • Supports Node.js v12.16.2+
  • Handles node: import prefixes
  • Resolves tsconfig.json paths

Tip:

cjs-loader doesn't hook into dynamic import() calls.

Use this with esm-loader for import() support. Alternatively, use tsx to handle them both automatically.

Install

npm install --save-dev @esbuild-kit/cjs-loader

Usage

Pass @esbuild-kit/cjs-loader into the --require flag

node -r @esbuild-kit/cjs-loader ./file.js

TypeScript configuration

The following properties are used from tsconfig.json in the working directory:

  • strict: Whether to transform to strict mode
  • jsx: Whether to transform JSX

    Warning: When set to preserve, the JSX syntax will remain untransformed. To prevent Node.js from throwing a syntax error, chain another Node.js loader that can transform JSX to JS.

  • jsxFactory: How to transform JSX
  • jsxFragmentFactory: How to transform JSX Fragments
  • jsxImportSource: Where to import JSX functions from
  • allowJs: Whether to apply the tsconfig to JS files
  • paths: For resolving aliases

Custom tsconfig.json path

By default, tsconfig.json will be detected from the current working directory.

To set a custom path, use the ESBK_TSCONFIG_PATH environment variable:

ESBK_TSCONFIG_PATH=./path/to/tsconfig.custom.json node -r @esbuild-kit/cjs-loader ./file.js

Cache

Modules transformations are cached in the system cache directory (TMPDIR). Transforms are cached by content hash so duplicate dependencies are not re-transformed.

Set environment variable ESBK_DISABLE_CACHE to a truthy value to disable the cache:

ESBK_DISABLE_CACHE=1 node -r @esbuild-kit/cjs-loader ./file.js

Related