tsconfig-paths

tsconfig-paths bridges the gap between TypeScript’s compile-time path mapping and Node.js’s runtime module resolution. When a project uses the paths field in tsconfig.json or jsconfig.json to declare custom import aliases, tsc resolves them fine at build time, but plain Node has no idea those aliases exist — it only walks up through node_modules. This package patches Module._resolveFilename so aliased imports resolve to their real, on-disk locations at runtime.

It ships both a zero-config loader invoked with Node’s -r tsconfig-paths/register flag (or through ts-node/mocha --require), and a small programmatic API (register, loadConfig, createMatchPath, createMatchPathAsync) for tools that want to build tsconfig-aware path resolution into a bundler, test runner, or custom module loader rather than patch Node’s require chain directly.

What You Get

• Runtime path resolution - patches Module._resolveFilename so aliased imports (@app/*, ~/utils, etc.) resolve to their real file locations when running compiled or ts-node code.
• Programmatic API - createMatchPath/createMatchPathAsync and matchFromAbsolutePaths/matchFromAbsolutePathsAsync for building your own path resolver into a bundler or test runner.
• Config auto-discovery - loadConfig/configLoader walk up from a given cwd to find and parse the nearest tsconfig.json or jsconfig.json, honoring TS_NODE_PROJECT and TS_NODE_BASEURL environment overrides.
• Zero-setup CLI hook - drop-in -r tsconfig-paths/register flag works with plain node, ts-node, and mocha --require, with no code changes needed in the consuming project.

Common Use Cases

• Running ts-node scripts with path aliases - a Node.js backend project defines @services/* and @models/* in tsconfig.json and needs those aliases to work when executing TypeScript directly with ts-node.
• Executing compiled output outside a bundler - a library builds with tsc and ships plain JS to lib/, but the compiled files still reference path aliases that only tsc understood, so tsconfig-paths/register is required at the process entry point.
• Test runners without built-in alias support - a Jest or Mocha suite imports modules via @app/* aliases; tsconfig-paths resolves them without duplicating the mapping in a separate moduleNameMapper config.
• Custom module loaders and bundlers - a tool author uses createMatchPath directly to implement tsconfig-aware resolution inside their own Webpack loader or CLI, without pulling in the full register() monkey-patch.

Under The Hood

Architecture

The package is a thin pipeline of single-purpose modules rather than one monolithic resolver: tsconfig-loader.ts locates and parses tsconfig.json/jsconfig.json (including extends chains), config-loader.ts normalizes that into a baseUrl+paths result (or accepts explicit params, bypassing file discovery entirely), mapping-entry.ts turns the paths object into sorted match rules, and match-path-sync.ts/match-path-async.ts walk those rules against a requested module specifier via try-path.ts to find a real file on disk. register.ts is the only piece that reaches outside this pipeline — it monkey-patches Node’s internal Module._resolveFilename and returns an undo function, keeping the invasive part isolated to one file and one call site. Nothing else in the core resolution logic touches global state, so createMatchPath can be reused standalone by other tools.

Tech Stack

Written in TypeScript (strict-ish config: noImplicitAny, strictNullChecks, noUnusedLocals/Parameters) targeting ES5/CommonJS for broad Node compatibility, with tsc compiling src/ to lib/ for the published package. Runtime dependencies are deliberately minimal — json5 for lenient tsconfig parsing (tsconfig.json commonly contains comments and trailing commas), strip-bom for BOM-safe file reads, and minimist for parsing the --project/-P CLI flag when register() is invoked without explicit params. Builds and tests run through Jest with ts-jest, linting via ESLint with the TypeScript parser and Prettier, and CI (GitHub Actions) runs the lint and test suite across Node 14/16/18 on Ubuntu.

Code Quality

Each core module (config-loader, filesystem, mapping-entry, match-path-sync, match-path-async, try-path, tsconfig-loader) has a dedicated Jest test file, and the tsconfig-loader and try-path tests in particular are extensive, covering extends chains, environment-variable overrides, and multi-candidate file resolution. Types are strict for a small library — noImplicitAny and strictNullChecks are on, public functions have explicit return types, and internal helpers (Filesystem.ReadJsonSync, MatchPath) are exported as named interfaces rather than left implicit. Error handling favors returning a discriminated resultType: "success" | "failed" union over throwing, which keeps register()’s failure path (falling back to a no-op with a console warning) explicit and testable rather than relying on caught exceptions.

What Makes It Unique

Rather than reimplement its own module system or require a build-step transform (as some alias-rewriting tools do), it works by patching a single well-known Node internal (Module._resolveFilename) at the exact point Node already does resolution — meaning it composes with ts-node, plain node -r, and test runners’ --require hooks with no separate loader or transform pass needed, and the same underlying createMatchPath primitive is exposed for tools that want tsconfig-aware resolution without adopting the monkey-patch at all.