{"id":13150,"library":"esm-loader-typescript","title":"ESM Loader for TypeScript","description":"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.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/brev/esm-loaders","tags":["javascript","esm","esmodule","loader","chainable","import","typescript"],"install":[{"cmd":"npm install esm-loader-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add esm-loader-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add esm-loader-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for chaining this loader with others and for advanced configuration via .loaderrc.js.","package":"node-esm-loader","optional":true}],"imports":[{"note":"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.","wrong":"import 'esm-loader-typescript'","symbol":"esm-loader-typescript","correct":"NODE_OPTIONS=\"--loader esm-loader-typescript\" node index.ts"},{"note":"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\"`.","wrong":"const { register } = require('node:module');","symbol":"register","correct":"import { register } from 'node:module'; register('esm-loader-typescript', import.meta.url);"},{"note":"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.","wrong":"Trying to pass these options directly via `NODE_OPTIONS` environment variable string.","symbol":"{ loader: 'esm-loader-typescript', options: { ... } }","correct":"export default { loaders: [{ loader: 'esm-loader-typescript', options: { config: 'tsconfig-custom.json', debug: true } }] };"}],"quickstart":{"code":"npm install --save-dev esm-loader-typescript node-esm-loader\n\n# Create your TypeScript source file\ncat << EOF > ./index.ts\nconst words: string = 'hello world';\nconsole.log(words);\nEOF\n\n# Create the .loaderrc.js configuration file\ncat << EOF > ./.loaderrc.js\nexport default {\n  loaders: [\n    {\n      loader: 'esm-loader-typescript',\n      options: {\n        debug: true, // Optional: enable debug logging\n        // config: 'tsconfig-custom.json' // Optional: specify a custom tsconfig file\n      }\n    }\n  ]\n};\nEOF\n\n# Run with node-esm-loader (works for all Node.js versions 16+)\nNODE_OPTIONS=\"--import node-esm-loader/register\" node index.ts\n\n# Expected output: 'hello world'","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"The 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>'.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This loader is explicitly stated as not suitable for production use due to its reliance on experimental Node.js features and potential for instability.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"The `esm-loader-typescript` is not correctly activated or configured in the `NODE_OPTIONS` environment variable.","error":"Error [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".ts\" for <path/to/file.ts>"},{"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);`.","cause":"You are using the deprecated `--loader` flag with Node.js versions 20.7 or higher.","error":"(node:xyz) Warning: The --loader <loader> flag is deprecated. Use a custom 'import' hook instead."},{"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`.","cause":"A `tsconfig.json` file was not found, or an incorrect path was specified for the `config` option within the `.loaderrc.js` file.","error":"TypeError: Cannot read properties of undefined (reading 'config')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}