Paths in tsconfig.json: What's Under the Hood of TypeScript

How Aliases in TypeScript Save Hours of Your Life

Have you ever written something like import UserService from '../../../../../services/UserService'? If yes — you know the pain. Your eyes glaze over, refactoring becomes a nightmare, and any file move breaks the entire import chain. Fortunately, TypeScript (and its configuration file tsconfig.json) offers an elegant solution — paths.

But here's the question: how does it work under the hood? Why, after defining the alias "@/*", can you write import { UserService } from '@/services/UserService'? And most importantly — why does it sometimes not work without additional bundler configuration (webpack, Vite, Rollup)?

In this article, we won't just show you how to configure paths in tsconfig.json. We'll look inside the mechanism, understand path mapping, learn how TypeScript resolves modules, and avoid common mistakes.

What are paths in tsconfig.json?

Paths is a section in tsconfig.json that allows you to define custom mappings between import aliases and real file paths. Simply put, you tell TypeScript: "When you encounter an import starting with @utils/, actually look for the file in the src/utils/ folder."

Here's what it looks like in code:

// tsconfig.json\n{\n  "compilerOptions": {\n    "baseUrl": ".",\n    "paths": {\n      "@/*": ["src/*"],\n      "@utils/*": ["src/utils/*"],\n      "@components/*": ["src/components/*"]\n    }\n  }\n}\n

Now, instead of terrible relative paths, you write:

// Before (nightmare)\nimport { formatDate } from '../../../../utils/dateHelpers';\n\n// After (beautiful)\nimport { formatDate } from '@utils/dateHelpers';\n

You'll agree, the difference is colossal. But how does TypeScript know where to go?

How Module Resolution Works Under the Hood

To understand path mapping in TypeScript, you need to understand the basic mechanism of resolution. When TypeScript compiles your code, it uses a strategy similar to Node.js, but with additional capabilities.

The process looks like this:

\n
1. Check for an absolute path (starts with /) — if yes, search from the file system root.
\n
2. Check for a relative path (starts with ./ or ../) — resolves relative to the current file.
\n
3. Check for an alias from paths — if the import starts with a prefix defined in paths, TypeScript replaces it with the corresponding path from the mapping.
\n
4. Search in node_modules — if nothing matches, it looks for the module as an npm package.
\n

The key point: TypeScript itself does not change the physical paths in the compiled JavaScript. It just checks types and throws errors if a file is not found. Replacing aliases with real paths at runtime is the job of the bundler (webpack, Vite, tsc-alias).

Why Don't paths Work Out of the Box?

Here's the most common question on Stack Overflow: "I configured paths, but when I run the application, I get a 'Cannot find module' error." The reason is simple: TypeScript is a transpiler, not a bundler.

When you run tsc, it generates JS files but leaves aliases untouched. For example, import { foo } from '@utils/bar' will remain in the JS as is. Node.js (or the browser) has no idea what @utils is and throws an error.

To fix this, you need to use one of the following solutions:

\n
• tsc-alias — a utility that replaces aliases with real paths after compilation.
\n
• module-alias — an npm package for registering aliases in N