olalonde / tsc-module-loader

Custom Node.js ESM loader that uses TypeScript's module resolution under the hood.

tsc-module-loader

Node.js custom ESM loader that uses the module resolution algorithm of the TypeScript compiler. It reads your tsconfig.json file, so it doesn't require any custom configuration. Things like like compilerOptions.paths will just work™. With this loader, if your import works at compile time, it will work at runtime.

Usage

npm install --save tsc-module-loader
node --experimental-loader tsc-module-loader build/some-file.js

Alternatively, you can register the loader programmatically in your code.

Why?

It solves a common issue and complaint among TypeScript developers. Importing a .js file feels weird when all your source files actually have the .ts extension:

import foo from "./bar.js";

However, if you omit the .js extension, Node.js will not be able to locate the module.

import foo from "./bar";

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/bar'  imported from ...
Did you mean to import /path/to/bar.js?
    at new NodeError (node:internal/errors:405:5)
    at finalizeResolution (node:internal/modules/esm/resolve:226:11)
    at moduleResolve (node:internal/modules/esm/resolve:838:10)
    ...

A current solution is to use tsc-alias as a post-compile step but it can be buggy and requires custom configuration. Another alternative is to use node --experimental-specifier-resolution=node but it will break if your tsconfig.json uses custom module resolution configuration like compilerOptions.paths.

The goal of this loader is that if an import works in TypeScript, it should also work at runtime. It does this by using TypeScript library functions to read your tsconfig.json and doing the module resolution.

Warning: custom ESM loaders are currently an experimental feature.