Registry / devops / tsconfig-paths

tsconfig-paths

JSON →
library4.2.0jsnpmunverified

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-paths
INSTALL
IMPORT
SIG · TSCONFIG-PATHS
T
tsconfig-paths
devopsjavascriptv4.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

register for side-effects
require('tsconfig-paths/register')
import '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)
import { register } from 'tsconfig-paths'
const register = require('tsconfig-paths').register
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
import { createMatchPath } from 'tsconfig-paths'
const createMatchPath = require('tsconfig-paths').createMatchPath
Used for advanced scenarios where you need to create a custom path matching function, separate from the global registration. Supports both CJS and ESM.

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();
Debug
Known issues
breakingWhen 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"`.
affects: >=4.0.0
gotchaIncorrect `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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module '@alias/my-module' from 'path/to/my-file.js'
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')
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
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`.
Upgrade
Version history
4.2.0latest on npm
Audit
Dependencies
ts-nodeoptionalCommonly used alongside tsconfig-paths for executing TypeScript files directly with path alias support.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
tsconfig-paths — npm install tsconfig-paths · libregistry