Path aliases can compile cleanly while failing at runtime because baseUrl was originally designed for AMD loaders, not as a universal Node alias system. TypeScript 6 now deprecates the option ahead of TypeScript 7.

The useful question is not whether the release sounds modern. It is whether the changed default or capability affects the way your project installs, compiles, resolves modules, or runs in production.

Quick answer

Remove unnecessary baseUrl, make paths relative to the tsconfig where possible, and configure the same alias in the runtime or bundler. Prefer package imports or workspace packages for aliases that cross package boundaries.

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

what changed

baseUrl remains available in TypeScript 6 but is deprecated and planned for removal in TypeScript 7. The experimental ts5to6 tool can help adjust baseUrl and rootDir configurations.

This is a version-specific change. Pin the tool or runtime while migrating so a teammate and CI do not test a different contract by accident.

where teams will notice it

Editor resolution is only one layer. Node, test runners, bundlers, and generated declaration files must agree, or aliases become deployment-only failures.

A small smoke test is more useful than assuming the changelog covers your architecture. Reproduce the workflow from a clean checkout with the same command production uses.

a safe migration

  1. List aliases and their consumers.
  2. Remove aliases used by only one or two files.
  3. Convert cross-package aliases to package exports/imports.
  4. Test emitted code outside the editor.

Change one resolution or security boundary at a time. That keeps failures attributable and makes rollback straightforward.

the mistake to avoid

Do not remove baseUrl and assume the runtime problem is solved. TypeScript paths still does not rewrite emitted imports by itself.

Avoid broad compatibility switches unless they are temporary, documented, and assigned a removal date. A migration that merely hides the warning will return as a harder TypeScript, Node, or npm upgrade later.

how to verify the result

Build, inspect emitted import strings, and run the output with the real production command. Test declaration consumers if the project publishes a library.

Record the tool version and verification command in the pull request. That gives reviewers evidence and gives the next upgrade a known baseline.

rollout note

Ship the change in a small pull request that records the old behavior, the new behavior, and the rollback command. For an application, test the production image rather than only the developer machine. For a library, install the packed tarball in a tiny consumer project. Keep the previous lockfile or compiler configuration available until CI, deployment, and one real workflow have all passed.

That evidence makes the upgrade reviewable. It also prevents a later failure from being blamed vaguely on the entire major release when one setting or experimental flag was responsible.

official reference

Check the linked documentation again before upgrading production. Current-release features and announced security timelines can change in later patch releases.