Bumping to TypeScript 7? Catch what tsgo breaks in your repo before CI does

#typescript #javascript #webdev #tooling

TypeScript 7.0 went GA on July 8 — the native Go compiler ("tsgo"), ~10x faster.
Two things bite the moment you bump typescript to ^7:

No programmatic Compiler API (deferred to 7.1). Anything that does
import * as ts from "typescript" and calls into the compiler breaks:
vue-tsc/Volar, Astro, Svelte, MDX, Angular template checking, ts-node,
ts-morph, typescript-eslint, ts-jest, typedoc, @microsoft/api-extractor…
Removed tsconfig.json options. baseUrl, target: "es5", legacy
module / moduleResolution (node/classic), esModuleInterop: false
and a dozen more are now hard errors — and strict is on by default.

The failure mode is nasty: a green local install, then a CI type-check that dies
deep in a build with createProgram is not a function or an unknown-option error.

I wanted a pre-flight check for one question — what in my repo breaks if I move
to 7? — from files I already have. So I built ts7-compat-guard.

What it does

It reads package.json and tsconfig.json (only — no source scanning) and
reports three things:

=== TypeScript 7.0 / tsgo Readiness ===
  typescript ^7.0.2 → TypeScript 7.0 detected (via devDependencies)

  [dependencies]
  CONFLICT: typescript-eslint — reads types via the Compiler API, absent in 7.0 until 7.1
    Fix: Run against @typescript/typescript6, or pin typescript to ^6.x

  [tsconfig.json]
  CONFLICT: baseUrl — baseUrl removed (tsconfig.json:6)
    Fix: Delete baseUrl and rewrite paths relative to the config file

  [advisories]  (behavioural risks — do not fail the build)
  ADVISORY: emitDecoratorMetadata support on tsgo is unconfirmed (tsconfig.json:9)

  2 conflict(s) · 1 advisory(ies) — builds will break under TypeScript 7.0.

Run it:

npx ts7-compat-guard              # scan ./package.json + ./tsconfig.json
npx ts7-compat-guard --recursive  # monorepo
npx ts7-compat-guard --sarif-file ts7.sarif   # GitHub code scanning

Or gate CI with the Action (tsconfig findings arrive as file annotations on the
exact line):

- uses: Booyaka101/ts7-compat-guard@v2
  with:
    mode: fail

Two design choices worth calling out

Config-only, so no false positives. It never parses your source, so it can't
cry wolf about a const enum or a decorator it half-understood. Every finding is
provable from your manifest or compiler config.

Advisories ≠ conflicts. Some things TS7 changes but can't be proven to break
your code — strict going default-on, or emitDecoratorMetadata (the native
compiler's metadata emit is still unresolved upstream).
Those are advisories that never fail your build, kept separate from hard
conflicts. I'd rather under-claim than flag you for something that turns out fine.

The honest caveat

This is a transitional tool. When TS 7.1 restores the stable Compiler API and
the ecosystem widens its peer ranges, most of these conflicts evaporate. It's most
useful right now, in the window between 7.0 and 7.1, when you want to upgrade
without a surprise red CI.