tsc-module-loader

0.0.1 verified Fri May 01 auth: no javascript

A Node.js custom ESM loader that mimics the TypeScript compiler's module resolution algorithm, enabling seamless use of TypeScript path aliases (e.g., paths and baseUrl in tsconfig.json) at runtime without a post-compile step. Version 0.0.1 is the initial and only release. It works by reading tsconfig.json automatically, eliminating the need for manual configuration. Unlike tsc-alias, which requires additional setup and may have bugs, this loader provides a direct, zero-config solution. Note: custom ESM loaders remain experimental in Node.js.

Common errors

error TypeError [ERR_QUICKSWITCH_INVALID]: Invalid value for the --experimental-loader flag ↓

cause Using an older Node.js version that doesn't support --experimental-loader or the flag syntax changed.

fix

Use a newer Node.js version (>=18.19.0 or >=20.0.0) and ensure the flag is spelled correctly.

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'tsc-module-loader' ↓

cause The loader package is not installed or node_modules is not in the correct path.

fix

Run 'npm install tsc-module-loader' in your project root. If using a monorepo, ensure the package is installed in the same directory as the execution.

error TypeError: ts.resolveModuleName is not a function ↓

cause The installed version of TypeScript may be incompatible (e.g., v5+ changed internal APIs) or the loader expects a specific TypeScript version.

fix

Ensure you have TypeScript installed as a dependency (npm install typescript) and use a compatible version. The loader was tested with TypeScript 4.x.

Warnings

gotcha Experimental feature: Custom ESM loaders are an experimental Node.js feature and may change in future versions. ↓

fix Use Node.js >=18.19 or >=20.0 for --experimental-loader support. Monitor Node.js changelog for changes to loader behavior.

breaking Node.js version requirements: The --experimental-loader flag requires Node.js at least v18.19.0 or v20.0.0. ↓

fix Upgrade Node.js to v18.19.0+, v20.0.0+, or v21.0.0+.

gotcha Works only with ES modules: The loader only applies to .js and .mjs files loaded as ES modules. CommonJS files are not affected. ↓

fix Ensure your entry point and imported files are ES modules (type: 'module' in package.json or .mjs extension).

Install

npm install tsc-module-loader

yarn add tsc-module-loader

pnpm add tsc-module-loader

Imports

tsc-loader
wrong
```
node -r tsc-loader build/some-file.js
```
correct
```
node --experimental-loader tsc-loader build/some-file.js
```
Must be used as an ESM loader, not a require hook. Use --experimental-loader or --loader (Node 20+)

Quickstart

Shows how to install the loader, configure path aliases in tsconfig.json, compile TypeScript, and run with the ESM loader to resolve aliases at runtime.

// Install the loader
npm install tsc-module-loader

// Create a simple TypeScript file with a path alias in tsconfig.json
// tsconfig.json:
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["src/utils/*"]
    }
  }
}

// src/index.ts:
import { helper } from '@utils/helper';
console.log(helper());

// Compile with tsc, then run with loader
npx tsc
node --experimental-loader tsc-module-loader build/index.js