Registry / devops / esm-loader-typescript

esm-loader-typescript

library1.0.6jsnpmunverified

esm-loader-typescript is a Node.js ESModule loader designed for on-the-fly transpilation of TypeScript (`.ts`) files within an ESModule environment. It leverages Node.js's experimental loader API, facilitating direct import of TypeScript files without a pre-compilation step. Currently at version 1.0.6, the package is primarily suited for development and testing workflows, with an explicit warning against production use due to the inherent instability and potential for breaking changes in Node.js's experimental loader API. It supports two main modes of operation: standalone activation via `NODE_OPTIONS` (using `--loader` for Node.js < 20.7 or `--import` with a registration file for Node.js >= 20.7), and a chainable mode using `node-esm-loader` and a `.loaderrc.js` configuration. Its key differentiators include simple integration into existing ESM projects, the ability to specify a custom `tsconfig.json` or enable debug logging via options, and its role as a building block for more complex loader chains.

devops

npm install esm-loader-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · ESM-LOADER-TYPESCR

esm-loader-typescript

devopsjavascriptv1.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esm-loader-typescript

✓ NODE_OPTIONS="--loader esm-loader-typescript" node index.ts

✗ import 'esm-loader-typescript'

This refers to the string identifier used to activate the loader, either directly via Node's `--loader` flag (deprecated in Node >= 20.7) or through `node-esm-loader`'s configuration.

✓ import { register } from 'node:module'; register('esm-loader-typescript', import.meta.url);

✗ const { register } = require('node:module');

This is the current, recommended way to register ESModule loaders in Node.js versions 20.7 and above, typically used within a separate `register.js` file invoked by `NODE_OPTIONS="--import ./register.js"`.

{ loader: 'esm-loader-typescript', options: { ... } }

✓ export default { loaders: [{ loader: 'esm-loader-typescript', options: { config: 'tsconfig-custom.json', debug: true } }] };

✗ Trying to pass these options directly via `NODE_OPTIONS` environment variable string.

Used when `esm-loader-typescript` is chained with `node-esm-loader` for advanced configuration like specifying a custom `tsconfig.json` or enabling debug mode. This object is part of a `.loaderrc.js` configuration file.

This quickstart demonstrates how to install and configure `esm-loader-typescript` using `node-esm-loader` to transpile and run a TypeScript file directly with Node.js.

npm install --save-dev esm-loader-typescript node-esm-loader # Create your TypeScript source file cat << EOF > ./index.ts const words: string = 'hello world'; console.log(words); EOF # Create the .loaderrc.js configuration file cat << EOF > ./.loaderrc.js export default { loaders: [ { loader: 'esm-loader-typescript', options: { debug: true, // Optional: enable debug logging // config: 'tsconfig-custom.json' // Optional: specify a custom tsconfig file } } ] }; EOF # Run with node-esm-loader (works for all Node.js versions 16+) NODE_OPTIONS="--import node-esm-loader/register" node index.ts # Expected output: 'hello world'

Debug

Known issues

breakingThe underlying Node.js ESModule Loader API is considered experimental and subject to breaking changes. This package's functionality may be unstable across Node.js versions or future releases.

fix

Monitor Node.js release notes for loader API changes and update 'esm-loader-typescript' accordingly. Avoid using in production environments where stability is critical.

affects: >=1.0.0

gotchaThe method for activating ESModule loaders differs significantly between Node.js versions. Node.js < 20.7 uses '--loader', while Node.js >= 20.7 requires '--import <path/to/register.js>'.

fix

For Node.js < 20.7, use 'NODE_OPTIONS="--loader esm-loader-typescript"'. For Node.js >= 20.7, create a 'register.js' file with 'import { register } from "node:module"; register("esm-loader-typescript", import.meta.url);' and use 'NODE_OPTIONS="--import ./register.js"'. Alternatively, use 'node-esm-loader' which abstracts these differences.

affects: >=1.0.0

gotchaThis loader is explicitly stated as not suitable for production use due to its reliance on experimental Node.js features and potential for instability.

fix

Restrict usage to development and testing environments. For production, pre-compile TypeScript or use established solutions like ts-node with appropriate production configurations and stability guarantees.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for <path/to/file.ts>

The `esm-loader-typescript` is not correctly activated or configured in the `NODE_OPTIONS` environment variable.

fix

Ensure `NODE_OPTIONS` is correctly set (e.g., `--loader esm-loader-typescript` for Node < 20.7, or `--import ./register.js` for Node >= 20.7, or `--import node-esm-loader/register` with a `.loaderrc.js` config).

(node:xyz) Warning: The --loader <loader> flag is deprecated. Use a custom 'import' hook instead.

You are using the deprecated `--loader` flag with Node.js versions 20.7 or higher.

fix

Update your command to use `NODE_OPTIONS="--import ./register.js"` where `register.js` is a file containing `import { register } from 'node:module'; register('esm-loader-typescript', import.meta.url);`.

TypeError: Cannot read properties of undefined (reading 'config')

A `tsconfig.json` file was not found, or an incorrect path was specified for the `config` option within the `.loaderrc.js` file.

fix

Ensure `tsconfig.json` exists in the project root or provide the correct path using `{ loader: 'esm-loader-typescript', options: { config: 'path/to/your-tsconfig.json' } }` in your `.loaderrc.js`.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

node-esm-loaderoptionalRequired for chaining this loader with others and for advanced configuration via .loaderrc.js.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/brev/esm-loaders ↗

packagehttps://www.npmjs.com/package/esm-loader-typescript ↗