Registry / devops / tsc-module-loader

tsc-module-loader

library0.0.1jsnpmunverified

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.

devops

npm install tsc-module-loader

package ↗

INSTALL

IMPORT

SIG · TSC-MODULE-LOADER

tsc-module-loader

devopsjavascriptv0.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

tsc-loader

✓ node --experimental-loader tsc-loader build/some-file.js

✗ node -r tsc-loader build/some-file.js

Must be used as an ESM loader, not a require hook. Use --experimental-loader or --loader (Node 20+)

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

Debug

Known issues

gotchaExperimental 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.

affects: all

breakingNode.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+.

affects: <18.19.0 || <20.0.0

gotchaWorks 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).

affects: all

Errors

Common errors & fixes

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

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 [ERR_MODULE_NOT_FOUND]: Cannot find module 'tsc-module-loader'

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.

TypeError: ts.resolveModuleName is not a function

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.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

typescriptrequiredUses TypeScript's own resolution logic (ts.resolveModuleName) via tsconfig.json parsing

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/tsc-module-loader ↗