{"id":12193,"library":"tsconfig-paths","title":"TypeScript Path Alias Resolver","description":"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.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/dividab/tsconfig-paths","tags":["javascript","typescript"],"install":[{"cmd":"npm install tsconfig-paths","lang":"bash","label":"npm"},{"cmd":"yarn add tsconfig-paths","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsconfig-paths","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used alongside tsconfig-paths for executing TypeScript files directly with path alias support.","package":"ts-node","optional":true}],"imports":[{"note":"This is a CommonJS-style side-effect import designed to be loaded via Node's `--require` flag or a `require()` call. While ESM `import` statements can load CommonJS modules, `--require` is the idiomatic way to activate it for the entire process.","wrong":"import 'tsconfig-paths/register'","symbol":"register for side-effects","correct":"require('tsconfig-paths/register')"},{"note":"For programmatic use, `register` takes configuration objects for `baseUrl` and `paths`. Both CommonJS `require` and ES Module `import` are supported, but prefer named imports for clarity in modern Node.js.","wrong":"const register = require('tsconfig-paths').register","symbol":"register (API)","correct":"import { register } from 'tsconfig-paths'"},{"note":"Used for advanced scenarios where you need to create a custom path matching function, separate from the global registration. Supports both CJS and ESM.","wrong":"const createMatchPath = require('tsconfig-paths').createMatchPath","symbol":"createMatchPath","correct":"import { createMatchPath } from 'tsconfig-paths'"}],"quickstart":{"code":"const tsConfig = require('./tsconfig.json');\nconst { register } = require('tsconfig-paths');\n\n// Example tsconfig.json content:\n// {\n//   \"compilerOptions\": {\n//     \"baseUrl\": \".\",\n//     \"paths\": {\n//       \"@utils/*\": [\"src/utils/*\"],\n//       \"@config\": [\"src/config/index.ts\"]\n//     }\n//   }\n// }\n\n// 1. Using the CLI with Node.js:\n// To run a JavaScript file compiled from TypeScript with path aliases:\n// node -r tsconfig-paths/register main.js\n\n// 2. Using the CLI with ts-node:\n// To run a TypeScript file directly with path aliases:\n// ts-node -r tsconfig-paths/register main.ts\n\n// 3. Programmatic registration for more control:\n// This is useful if your tsconfig.json is not in the CWD or you need custom settings.\n\nconst baseUrl = process.env.TS_NODE_BASEURL ?? tsConfig.compilerOptions.baseUrl ?? './';\nconst cleanup = register({\n  baseUrl,\n  paths: tsConfig.compilerOptions.paths\n});\n\nconsole.log('tsconfig-paths registered successfully.');\n\n// Your application logic that uses path aliases would go here.\n// For example, if you had '@utils/logger' mapped to 'src/utils/logger.ts'\n// import { log } from '@utils/logger';\n// log('Application started');\n\n// When path registration is no longer needed (e.g., in a long-running process that might reconfigure)\n// cleanup();","lang":"javascript","description":"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`."},"warnings":[{"fix":"Update your Mocha command to `mocha -r ts-node/register -r tsconfig-paths/register \"test/**/*.ts\"`.","message":"When using Mocha versions 4.0.0 or higher, the `--compiler` option was deprecated. Instead, you must use `--require` to load `ts-node/register` and `tsconfig-paths/register`, and explicitly specify TypeScript file extensions in your glob pattern.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"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.","message":"Incorrect `baseUrl` or `paths` configuration in `tsconfig.json` will lead to module resolution failures. `tsconfig-paths` relies directly on these settings, so any mismatch with actual file locations or incorrect wildcard usage will cause 'module not found' errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"The `tsconfig-paths/register` module must be loaded *before* any other modules that rely on path aliases. If your application code is loaded first, Node.js will attempt resolution before tsconfig-paths has a chance to hook into the module system.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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.","cause":"Node.js failed to resolve a module imported with a path alias, indicating tsconfig-paths either isn't loaded or is misconfigured.","error":"Error: Cannot find module '@alias/my-module' from 'path/to/my-file.js'"},{"fix":"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.","cause":"The `tsconfig.json` file could not be found or parsed when using programmatic API, or is missing the `compilerOptions` field.","error":"TypeError: Cannot read properties of undefined (reading 'compilerOptions')"},{"fix":"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`.","cause":"The `tsconfig.json` file could not be automatically located by `tsconfig-paths`.","error":"Error: tsconfig-paths: Could not load tsconfig.json. Config file: undefined"}],"ecosystem":"npm"}