{"id":26527,"library":"tsc-module-loader","title":"tsc-module-loader","description":"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.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install tsc-module-loader","lang":"bash","label":"npm"},{"cmd":"yarn add tsc-module-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsc-module-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Uses TypeScript's own resolution logic (ts.resolveModuleName) via tsconfig.json parsing","package":"typescript","optional":false}],"imports":[{"note":"Must be used as an ESM loader, not a require hook. Use --experimental-loader or --loader (Node 20+)","wrong":"node -r tsc-loader build/some-file.js","symbol":"tsc-loader","correct":"node --experimental-loader tsc-loader build/some-file.js"}],"quickstart":{"code":"// Install the loader\nnpm install tsc-module-loader\n\n// Create a simple TypeScript file with a path alias in tsconfig.json\n// tsconfig.json:\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@utils/*\": [\"src/utils/*\"]\n    }\n  }\n}\n\n// src/index.ts:\nimport { helper } from '@utils/helper';\nconsole.log(helper());\n\n// Compile with tsc, then run with loader\nnpx tsc\nnode --experimental-loader tsc-module-loader build/index.js","lang":"typescript","description":"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."},"warnings":[{"fix":"Use Node.js >=18.19 or >=20.0 for --experimental-loader support. Monitor Node.js changelog for changes to loader behavior.","message":"Experimental feature: Custom ESM loaders are an experimental Node.js feature and may change in future versions.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade Node.js to v18.19.0+, v20.0.0+, or v21.0.0+.","message":"Node.js version requirements: The --experimental-loader flag requires Node.js at least v18.19.0 or v20.0.0.","severity":"breaking","affected_versions":"<18.19.0 || <20.0.0"},{"fix":"Ensure your entry point and imported files are ES modules (type: 'module' in package.json or .mjs extension).","message":"Works only with ES modules: The loader only applies to .js and .mjs files loaded as ES modules. CommonJS files are not affected.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use a newer Node.js version (>=18.19.0 or >=20.0.0) and ensure the flag is spelled correctly.","cause":"Using an older Node.js version that doesn't support --experimental-loader or the flag syntax changed.","error":"TypeError [ERR_QUICKSWITCH_INVALID]: Invalid value for the --experimental-loader flag"},{"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.","cause":"The loader package is not installed or node_modules is not in the correct path.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'tsc-module-loader'"},{"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.","cause":"The installed version of TypeScript may be incompatible (e.g., v5+ changed internal APIs) or the loader expects a specific TypeScript version.","error":"TypeError: ts.resolveModuleName is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}