TypeScript 7 delivers the new native compiler and language server, but version 7.0 does not ship a stable programmatic compiler API. That matters to tools which import typescript to parse files, create programs, inspect types, or extend the language service. A project can therefore pass tsc while linting, code generation, documentation, or framework tooling still fails.

The official bridge is @typescript/typescript6. It exposes a tsc6 executable and re-exports the TypeScript 6 API, allowing the TypeScript 7 command-line compiler to coexist with API-dependent tools.

Quick answer

Install TypeScript 7 under an alias and make typescript resolve to the TypeScript 6 compatibility package for tools that still use the old API. Give each command an explicit name so nobody has to guess which compiler ran.

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  },
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:ts6": "tsc6 --noEmit",
    "lint": "eslint ."
  }
}

In this arrangement, the TypeScript 7 package provides tsc, while the compatibility package provides tsc6 and the API imported as typescript.

Find API consumers before changing aliases

Search direct dependencies, configuration, and custom scripts. Common consumers include type-aware ESLint tooling, API Extractor, typed documentation generators, custom transforms, schema generators, test transformers, and framework language services.

npm explain typescript
rg -n "from ['\"]typescript|require\\(['\"]typescript" \
  scripts tools packages

The lockfile may show many peer dependencies on TypeScript. That is a starting point, not proof of incompatibility. Run each important command and capture the actual error.

Make the compiler choice visible

Print versions in CI before executing checks:

npx tsc --version
npx tsc6 --version
node -e "console.log(require('typescript').version)"

Save these lines beside the build result. When a developer reports a diagnostic difference, the team should know whether it came from TypeScript 6, TypeScript 7, or an editor server.

Use separate CI jobs for the new compiler and legacy API tools. This prevents an alias change in one job from silently changing the other.

jobs:
  native-typecheck:
    steps:
      - run: npm ci
      - run: npm run typecheck
  api-dependent-tools:
    steps:
      - run: npm ci
      - run: npm run lint
      - run: npm run docs

Avoid two sources of truth

Running two compilers indefinitely creates ambiguity. Define which result blocks merges. During migration, TypeScript 6 can verify compatibility while TypeScript 7 is the primary type check, or the reverse if the framework still depends heavily on TypeScript 6.

Do not accept contradictory results without investigation. Reduce a difference to a small file, record both versions, and check whether the behavior comes from a TypeScript 6 default, a TypeScript 7 hard error for a deprecated option, or an actual compiler issue.

Use one shared tsconfig whenever possible. Separate configurations should exist only for documented incompatibilities, with a removal issue and owner.

Know when the bridge is no longer needed

TypeScript 7.1 is expected to introduce a new API, but tools still need time to adopt it. Track upstream support for every API consumer rather than removing TypeScript 6 based only on the TypeScript release number.

The exit checklist is:

  • linting and code generation support the new API or no longer import TypeScript;
  • framework editor tooling supports TypeScript 7;
  • CI invokes only one intended compiler;
  • npm explain typescript shows no dependency forcing the compatibility alias;
  • generated declarations and runtime tests remain stable.

Remove aliases and obsolete scripts in one reviewed change. A leftover tsc6 command can keep an old compiler alive unnoticed.

Record which binary each script invokes by printing its version in CI. A passing job labeled typecheck is weak evidence if maintainers cannot tell whether it ran the native compiler or the compatibility executable. Store both version lines beside the diagnostics artifact.

Also install from a clean lockfile in the test job. A developer machine may have a global tsc or cached package that hides an incorrect alias. The clean job proves another contributor receives the same two-tool arrangement from repository configuration alone.

Primary references

The side-by-side setup is useful because it separates compiler speed from ecosystem readiness. Use it deliberately, measure which tools still need TypeScript 6, and remove the bridge when those named dependencies move forward.