TypeScript tsconfig Paths: How Path Mapping Works with Webpack

By the end of this page, you will understand how TypeScript path mapping works, how to configure baseUrl and paths in tsconfig.json, and why tools like Webpack usually need matching alias configuration. You will also learn the difference between helping the TypeScript compiler find files and helping your runtime or bundler resolve imports correctly.

TypeScript supports path mapping through the compilerOptions.paths setting in tsconfig.json. This feature lets you replace long relative import paths with shorter, clearer aliases.

For example, instead of this:

import { Something } from "../../../../../lib/src/browser/utils/something";

You can write something like this:

import { Something } from "@lib/browser/utils/something";

To make that work, TypeScript usually needs two settings:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@lib/*": ["lib/src/*"]
    }
  }
}

Why this matters

Think of import paths like addresses.

A relative import such as:

../../../../../lib/src/browser/tool

is like giving turn-by-turn directions from your current location.

A path alias such as:

@lib/browser/tool

is like giving a saved place name such as "Office".

TypeScript can be taught that "Office" means lib/src. But if Webpack or Node has never heard of that nickname, it will not know where to go.

So:

• baseUrl and paths = teaching TypeScript the nickname
• Webpack alias = teaching the bundler the same nickname
• Runtime support = teaching the running app the same nickname if needed

The basic tsconfig.json setup looks like this:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "lib/*": ["lib/src/*"]
    }
  }
}

What each part means

• baseUrl: the starting directory for non-relative module names
• paths: custom alias rules
• lib/*: the alias pattern used in imports
• lib/src/*: the actual folder TypeScript should look in

Example import

With this config:

{
  "compilerOptions": {
    "baseUrl": 
     
       
    
  

Consider this tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@lib/*": ["lib/src/*"]
    }
  }
}

And this import:

import { formatDate } from "@lib/utils/date";

Step by step

1. TypeScript sees a non-relative import: @lib/utils/date.

2. It checks baseUrl and paths in tsconfig.json.

3. It finds a matching pattern:

   • alias pattern: @lib/*

Path mapping is especially useful in large or multi-package projects.

Monorepos

A monorepo may contain:

• shared UI libraries
• server utilities
• browser-only helpers
• universal modules used everywhere

Aliases help keep imports readable:

import { Button } from "@lib/ui/Button";
import { logger } from "@server/logging/logger";

Frontend applications

Instead of:

import { formatPrice } from "../../../../shared/utils/formatPrice";

You can use:

import { formatPrice } from "@shared/utils/formatPrice";

Backend services

In a Node or API project, aliases make service-layer imports cleaner:

import { validateUser } from "@core/validation/user";
import { db } from ;

In real projects, developers rarely use paths alone. They usually build a consistent module resolution strategy across tools.

Common patterns

1. Feature-based aliases

Instead of aliasing one huge root folder, teams often define aliases by responsibility:

{
  "paths": {
    "@components/*": ["src/components/*"],
    "@services/*": ["src/services/*"],
    "@utils/*": ["src/utils/*"]
  }
}

This makes architecture more obvious in imports.

2. Shared aliases across apps in a monorepo

A root tsconfig.base.json may define aliases once, and child projects extend it:

{
  "compilerOptions": {
     
     
       
    
  

1. Forgetting baseUrl

Many paths setups require baseUrl.

Broken example:

{
  "compilerOptions": {
    "paths": {
      "@lib/*": ["lib/src/*"]
    }
  }
}

Safer setup:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@lib/*": ["lib/src/*"]
    }
  }
}

2. Expecting to configure Webpack automatically

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@lib/*": ["lib/src/*"],
      "@browser/*": ["lib/src/browser/*"],
      "@server/*": ["lib/src/server/*"],
      "@universal/*": ["lib/src/universal/*"]
    }
  }
}

Quick rules

• Use baseUrl with paths.
• @alias/* maps to real/path/*.
• The should usually appear on both sides.

Is tsconfig.json enough to use path aliases?

Usually not. It is enough for TypeScript type checking and editor support, but bundlers like Webpack often need matching alias configuration.

Do I need baseUrl when using paths?

In most common setups, yes. It defines the base location from which non-relative imports are resolved.

Why does TypeScript compile, but Webpack says module not found?

Because TypeScript and Webpack resolve modules separately. Your alias is likely configured in tsconfig.json but not in Webpack.

Should I use lib/* or @lib/*?

@lib/* is usually clearer because it looks like a deliberate alias instead of a package name.

Can I use path aliases in a monorepo?

Yes. They are very common in monorepos for shared code, especially when combined with a base tsconfig file.

Do path aliases change the emitted JavaScript import paths?

Not by themselves in a way that solves runtime resolution everywhere. They mainly affect how TypeScript understands module paths.

Can I create separate aliases for browser, server, and universal code?

Yes. This is a practical way to make environment boundaries clear, for example @browser/*, , and .

• baseUrl — Works together with paths to resolve non-relative imports.
• Module resolution — Explains how TypeScript, Node, and bundlers locate imported files.
• Webpack resolve.alias — The Webpack feature that mirrors TypeScript path aliases.
• Monorepo structure — Important because aliases are especially useful in large shared codebases.
• Relative vs absolute imports — Helps explain why aliases improve readability.
• TypeScript compilerOptions — paths and baseUrl are both part of this configuration area.
• Jest moduleNameMapper — Test environments often need alias mapping too.
• Project references — Another TypeScript feature often used in larger monorepos.