Node package imports beginning with # provide runtime-aware aliases, but the #/ form previously produced friction in TypeScript projects. TypeScript 6 now recognizes these subpath mappings more naturally.

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

Define the alias in package.json under imports, point it at runtime files, and let TypeScript resolve the same contract. Keep the mapping inside the package that owns it.

{
  "imports": {
    "#/*": "./dist/*.js"
  }
}

import { loadConfig } from "#/config.js";

what changed

TypeScript 6 adds support for subpath imports starting with #/. Package imports are private mappings controlled by the current package, unlike public exports entries.

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

This can replace some tsconfig-only aliases because Node and TypeScript read compatible package metadata. Source-to-output mapping still needs care when development runs TypeScript directly.

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. Define one narrow import mapping.
  2. Confirm its runtime target exists after build.
  3. Use the same extension Node loads.
  4. Test from a file inside the owning package.

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

the mistake to avoid

Do not use imports to reach arbitrary files across workspace packages. Each package should expose a public contract or declare its own private mapping.

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 the package and run one emitted file that imports through #/. The test must use Node directly, not only an editor or test transformer.

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.