cjs-loader

Node.js require() hook for loading ESM & TypeScript.

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

Protip: use with esm-loader or tsx

cjs-loader only transforms CommonJS modules (.cjs/.cts or .js files in commonjs type packages).

To hook into import() calls or ES modules (.mjs/.mts extensions or .js files in module type packages), use this with esm-loader.

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

• tsx - Node.js runtime powered by esbuild using @esbuild-kit/cjs-loader and @esbuild-kit/esm-loader.

• @esbuild-kit/esm-loader - TypeScript to ESM transpiler using the Node.js loader API.

Sponsors