tsconfig-paths is a utility that provides runtime support for TypeScript's path mapping feature, allowing Node.js to resolve modules based on the `paths` configuration in `tsconfig.json`. This addresses the common issue where TypeScript compiles code successfully using path aliases (e.g., `@lib/utils`), but Node.js fails at runtime because it doesn't understand these mappings. The package, currently at version 4.2.0, functions by hooking into Node.js's module resolution system, typically via a `--require` flag (e.g., `node -r tsconfig-paths/register`) or through a programmatic API. While TypeScript handles `paths` during compilation, tsconfig-paths ensures these aliases work in development environments with `ts-node` or directly with compiled JavaScript, making it a critical tool for maintaining clean import paths and structured projects without additional build steps or manual path adjustments for runtime execution. Its release cadence is generally tied to bug fixes and compatibility updates, not a strict schedule.
npm install tsconfig-pathsVerified import paths — ran on the pinned version, not inferred.
Demonstrates both CLI usage for Node.js and ts-node, and programmatic API registration for finer control over path resolution, including `baseUrl` and `paths` from `tsconfig.json`.
Update your Mocha command to `mocha -r ts-node/register -r tsconfig-paths/register "test/**/*.ts"`.
Verify that your `tsconfig.json`'s `compilerOptions.baseUrl` is correctly set relative to the root of your project, and that `compilerOptions.paths` entries accurately map aliases to physical file paths. Ensure wildcard (`*`) usage is consistent.
Always pass `tsconfig-paths/register` as a `--require` flag to Node.js or `ts-node` (e.g., `node -r tsconfig-paths/register app.js`), or ensure programmatic `register()` calls happen at the very beginning of your application's entry point.
Ensure `tsconfig-paths/register` is correctly loaded via `node -r tsconfig-paths/register` or `ts-node -r tsconfig-paths/register`. Double-check `tsconfig.json` for correct `baseUrl` and `paths` entries, and confirm the alias matches a valid file path.
Verify that `tsconfig.json` exists in the expected location and is valid JSON. If using the programmatic API, ensure the path to `tsconfig.json` is correct and accessible.
If `tsconfig.json` is not in the current working directory, either move it, or use the programmatic API (`register({ baseUrl, paths })`) to explicitly provide the configuration. When using `ts-node`, you can set `process.env.TS_NODE_PROJECT` to point to your `tsconfig.json`.