TypeScript 7 Compatibility

A TypeScript major upgrade cannot be approved with one tsc --noEmit run. A library that only publishes declarations fails differently from a tool that executes the Compiler API. A framework may also run its own type checker, making a successful project tsc run different from a successful production build.

This procedure replaces "it is probably compatible" with "we ran this evidence at this version and boundary."

As of August 11, 2026, this repository has 79 direct external dependencies and uses TypeScript 6.0.3 in every workspace. The public packages use the same compiler to emit ESM JavaScript and declarations. The TS 7 routes below are an audit procedure for a future migration and are not applied to the current production configuration.

1. Freeze an exact inventory

Collect exact direct dependency versions from every workspace manifest and the lockfile. Decide on every direct dependency, then follow transitive packages that declare a TypeScript peer or import the Compiler API.

pnpm list -r --depth 0
rg '"typescript"' package.json pnpm-workspace.yaml apps packages
rg 'typescript/lib/typescript|require\\(.typescript.|from .typescript.' node_modules/.pnpm

Record more than package names: include the version, consuming workspace, production or development role, and scripts that execute it. A lockfile change creates a new verification target.

2. Classify the coupling first

The required evidence becomes clearer when dependencies are divided by boundary.

The absence of peerDependencies.typescript is not a support statement. Conversely, a peer range that includes 7 is insufficient until the API path and build used by the repository have run.

3. Separate official claims from local evidence

Start with versioned official documentation, release notes, published manifests, and source. Record repository typecheck, build, and test results in a separate evidence column. Do not present a local success as a vendor support commitment.

The TypeScript 7 announcement states that 7.0 has no stable Compiler API. It also advises embedded-language workflows such as MDX to remain on TypeScript 6 for now. That distinction is why source compatibility and toolchain compatibility require separate decisions.

4. Map ecosystem-specific migration routes

Not every package publishes a TS 7-specific guide. For tools coupled through the Compiler API, embedded languages, or declaration emit, find an official migration route. For the rest, use the repository's typecheck, build, packaging, and smoke-test boundaries as evidence.

All 79 current direct dependencies fit into the following migration domains.

The total is 79. Follow @nx/workspace and ts-morph as transitive dependencies. The repository does not currently import the TypeScript Compiler API at runtime, so a future consumer must add its own explicit compatibility evidence.

The important official routes are:

• TypeScript and Nx can run the TS 7 tsc alongside the TypeScript 6 API.
• Next.js 16.2.12 can run the TS 7 CLI during a production build with experimental.useTypeScriptCli.
• Oxlint type-aware linting requires TS 7 or newer and oxlint-tsgolint@7.
• TypeScript declaration emit runs in the same compiler boundary as JavaScript emit for the public packages.
• Vite and Playwright separate transformation from type checking, while Vitest invokes tsc in typecheck mode.
• Electron Forge's TypeScript configuration and Vite plugin require real Forge package and release DMG validation rather than relying on a compiler support statement.

Do not interpret the absence of a dedicated migration guide as lack of support. Conversely, packages that only expose declarations, such as React, CodeMirror, and Tailwind integrations, are not verified until the real application build passes.

5. Keep one production compiler

When any production boundary still needs the TypeScript 6 Compiler API, keep every tracked workspace on the latest stable TypeScript 6 release. A TS 7 candidate may be evaluated in a disposable copy or isolated branch, but do not commit compiler aliases or a split compiler tree as a production configuration.

pnpm exec tsc --version
pnpm list -r typescript --depth 0
pnpm exec nx show projects

The compiler version, the package imported as typescript, and framework-owned type checking must all resolve to the same workspace baseline. A successful isolated TS 7 CLI run is evidence for a future migration, not permission to mix compiler roles in the tracked workspace.

Even though Nx officially supports a side-by-side setup, a repository does not have to adopt that production topology. This repository still has MDX and a repository-owned content Compiler API boundary, so every workspace installs only TypeScript 6.0.3.

6. Surface configuration changes first

Remove temporary ignoreDeprecations settings on TypeScript 6, then inspect the new defaults and removed options in TypeScript 7. Compare the effective values of rootDir, types, module, moduleResolution, strict, noUncheckedSideEffectImports, and libReplacement.

pnpm exec tsc --showConfig -p tsconfig.json
pnpm exec tsc --noEmit --incremental false -p tsconfig.json

Run every tsconfig explicitly. A root check does not necessarily include application, Electron main process, package build, or test configurations.

7. Complete the verification ladder

Move from inexpensive checks to the actual delivery boundary.

1. tsc --noEmit for every tsconfig
2. A diagnostic run with skipLibCheck: false
3. Bundler and declaration emit
4. Unit, integration, and E2E tests
5. Framework-owned type checking and production builds
6. Watch mode and editor/LSP behavior
7. Electron/native packaging and smoke tests

skipLibCheck: false is a useful audit, but it does not have to be the normal release gate. Compare the same failures on TypeScript 6 to separate existing declaration debt from a TS 7 regression. A successful TS 7 check in a project that normally uses skipLibCheck: true does not prove that every transitive declaration is compatible.

Next.js 16.2.12's default checker looks for typescript/lib/typescript.js in its setup verification and calls createProgram and getPreEmitDiagnostics in its type checker. However, the official experimental.useTypeScriptCli option makes next build invoke the project's TS 7 tsc instead. Next.js is therefore no longer an absolute blocker, but an external TS 7 run without that option, or a plain tsc --noEmit, still does not replace a next build.

8. Record a decision and a recheck trigger

Every deferred or blocked decision needs a recheck trigger: name the release or test that would change the result. Preserve the verification date, exact versions, command, exit code, and first causal error.

9. Move the workspace as one boundary

Adopt a compiler major only after one candidate version passes every tsconfig, package build, framework build, editor and watch workflow, Nx release graph, and Electron packaging boundary. Update the workspace manifests and lockfile together, then run the full validation suite. Roll back the single version change if any required boundary fails.

In the historical audit, a uniform TS 7 setup failed at the Nx graph, the default Next.js checker, and the content Compiler API. Nx and Next.js now provide official migration routes, but the MDX and repository-owned content Compiler API boundaries remain. The current decision is to use only TypeScript 6.0.3 in every workspace and not apply TS 7 aliases or per-workspace compiler splits in production.

References

• Announcing TypeScript 7.0
• Nx TypeScript 7 side-by-side setup
• Next.js 16.2.12 useTypeScriptCli
• Next.js 16.2.12 TypeScript setup
• Oxlint type-aware linting
• TypeScript declaration
• Vite TypeScript
• Vitest type testing
• Playwright TypeScript
• Electron Forge TypeScript setup
• Repository compatibility audit