TypeScript Path Alias Resolver

Common errors

• Error: Cannot find module '@alias/my-module' from 'path/to/my-file.js'

  cause Node.js failed to resolve a module imported with a path alias, indicating tsconfig-paths either isn't loaded or is misconfigured.
  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.

• TypeError: Cannot read properties of undefined (reading 'compilerOptions')

  cause The `tsconfig.json` file could not be found or parsed when using programmatic API, or is missing the `compilerOptions` field.
  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.

• Error: tsconfig-paths: Could not load tsconfig.json. Config file: undefined

  cause The `tsconfig.json` file could not be automatically located by `tsconfig-paths`.
  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`.

Warnings

• breaking 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.
  Fix: Update your Mocha command to `mocha -r ts-node/register -r tsconfig-paths/register "test/**/*.ts"`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install tsconfig-paths npm
• yarn add tsconfig-paths yarn
• pnpm add tsconfig-paths pnpm

Imports

• register for side-effects
  wrong:

  import 'tsconfig-paths/register'

  correct:

  require('tsconfig-paths/register')

  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.
• register (API)
  wrong:

  const register = require('tsconfig-paths').register

  correct:

  import { register } from 'tsconfig-paths'

  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.
• createMatchPath
  wrong:

  const createMatchPath = require('tsconfig-paths').createMatchPath

  correct:

  import { createMatchPath } from 'tsconfig-paths'

  Used for advanced scenarios where you need to create a custom path matching function, separate from the global registration. Supports both CJS and ESM.

Quickstart

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`.

const tsConfig = require('./tsconfig.json');
const { register } = require('tsconfig-paths');

// Example tsconfig.json content:
// {
//   "compilerOptions": {
//     "baseUrl": ".",
//     "paths": {
//       "@utils/*": ["src/utils/*"],
//       "@config": ["src/config/index.ts"]
//     }
//   }
// }

// 1. Using the CLI with Node.js:
// To run a JavaScript file compiled from TypeScript with path aliases:
// node -r tsconfig-paths/register main.js

// 2. Using the CLI with ts-node:
// To run a TypeScript file directly with path aliases:
// ts-node -r tsconfig-paths/register main.ts

// 3. Programmatic registration for more control:
// This is useful if your tsconfig.json is not in the CWD or you need custom settings.

const baseUrl = process.env.TS_NODE_BASEURL ?? tsConfig.compilerOptions.baseUrl ?? './';
const cleanup = register({
  baseUrl,
  paths: tsConfig.compilerOptions.paths
});

console.log('tsconfig-paths registered successfully.');

// Your application logic that uses path aliases would go here.
// For example, if you had '@utils/logger' mapped to 'src/utils/logger.ts'
// import { log } from '@utils/logger';
// log('Application started');

// When path registration is no longer needed (e.g., in a long-running process that might reconfigure)
// cleanup();