Code TypeScript Module Resolution and Path Mapping

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

TypeScript module resolution and path mapping evidence helps code agents separate type-checker lookup success from runtime import success.

## Core Explanation

Agents often see an import path work in the editor but fail in Node, a test runner, or a bundler. TypeScript can be told how to resolve aliases for type checking, but emitted import strings may still need a compatible runtime or bundler configuration.

Useful evidence includes moduleResolution mode, baseUrl, paths, package.json exports, tsconfig inheritance, project references, bundler aliases, test runner resolver settings, and emitted JavaScript. Agents should not assume that a TypeScript path alias changes runtime behavior unless another tool is configured to honor the same mapping.

## Source-Mapped Facts

- TypeScript documentation says relative module specifiers are never affected by the baseUrl option. ([source](https://www.typescriptlang.org/docs/handbook/modules/reference))
- TypeScript documentation says node_modules package lookups are supported by all moduleResolution options except classic. ([source](https://www.typescriptlang.org/docs/handbook/modules/reference))
- TypeScript TSConfig documentation says paths remap imports to lookup locations but do not change how import paths are emitted by tsc. ([source](https://www.typescriptlang.org/tsconfig/paths.html))

## Further Reading

- [TypeScript Modules Reference](https://www.typescriptlang.org/docs/handbook/modules/reference)
- [TypeScript TSConfig paths](https://www.typescriptlang.org/tsconfig/paths.html)