TypeScript 7 Compatibility

Verify library declarations, Compiler API coupling, builds, and tooling before a compiler major upgrade.

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 September 3, 2026, this repository uses TypeScript 7.0.2 in every workspace. The public packages use the same compiler to emit Node-compatible ESM JavaScript and declarations, while the Web app uses Next.js's TypeScript CLI path. The procedure below records the adoption evidence and the revalidation criteria for the next compiler change.

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.

bun pm ls --all
rg '"typescript"' package.json bun.lock apps packages
rg 'typescript/lib/typescript|require\\(.typescript.|from .typescript.' node_modules

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.

Coupling	What to verify
Declaration consumer	TS 7 checks real imports and public types
CLI execution	`tsc`, build, and test commands execute with the TS 7 binary
Compiler API consumer	Code imports `createProgram`, `readConfigFile`, AST, or language-service APIs
Embedded language	MDX, Vue, Astro, or Svelte uses separate language tooling
Runtime or native	Node ABI and real execution still work

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 describes the native Go compiler and states that 7.0 has no stable Compiler API. This repository does not import that API directly and transforms MDX through Fumadocs's Bun plugin, so source compatibility and embedded-language toolchain compatibility remain 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.

Current direct dependencies fit into the following migration domains.

Domain	Representative direct dependencies	Evidence required for TS 7
Compiler	`typescript`	CLI checks, declaration emit, and framework integration
Next.js and content	`next`, `fumadocs-mdx`, `fumadocs-core`, `@types/mdx`	Next CLI checker, MDX compilation, and runtime content loading
Build, lint, and test	`esbuild`, `bun:test`, `oxlint`, `oxlint-tsgolint`, `@playwright/test`	Declaration emit, type-aware lint, unit tests, and E2E
CSS	`tailwindcss`, `@tailwindcss/postcss`, `postcss`, `tw-animate-css`	Next production CSS build
React and UI	`react`, `react-dom`, `@base-ui/react`, `lucide-react`, `cmdk`, `zod`	JSX declaration checks and real application builds
Development CLIs	`shadcn`	CLI smoke tests and an explicit TypeScript migration
Other declarations	`@excalidraw/excalidraw`, `@types/node`, `@types/react`, `@types/react-dom`	Compare with `skipLibCheck: false` and run application builds

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:

Next.js 16.3.1 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.
Playwright and Bun test separate TypeScript execution from type checking, so bun run typecheck remains a distinct release gate.

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 a production boundary needs a Compiler API that the current compiler does not provide, use the tool's official CLI route or defer adoption. A candidate compiler may be evaluated in a disposable copy or isolated branch, but do not commit compiler aliases or a split compiler tree as production configuration.

bun run tsc --version
bun pm ls --all | rg typescript

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.

This repository installs only TypeScript 7.0.2 across every workspace without a compiler alias. Next.js uses experimental.useTypeScriptCli: true, while Fumadocs tests and scripts use the fumadocs-mdx/bun plugin without introducing a Compiler API dependency.

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.

bun run tsc --showConfig -p tsconfig.json
bun run tsc --noEmit --incremental false -p tsconfig.json

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

7. Complete the verification ladder

Move from inexpensive checks to the actual delivery boundary.

tsc --noEmit for every tsconfig
A diagnostic run with skipLibCheck: false
Bundler and declaration emit
Unit, integration, and E2E tests
Framework-owned type checking and production builds
Watch mode and editor/LSP behavior

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.3.1'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

Decision	When to use it
Verified	An official range and the actual usage boundary pass on TS 7
Deferred	Any required API, framework, editor, or release boundary is unsupported
Blocked	The usage boundary fails in a uniform TS 7 configuration
TypeScript-independent	No Compiler API or TypeScript peer coupling exists
Inconclusive baseline	Existing failures prevent isolating a TS 7 regression

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, and editor and watch workflow. Update the workspace manifests and lockfile together, then run the full validation suite. Roll back the single version change if any required boundary fails.

The current adoption runs root and workspace type checks, public-package declaration emit, Bun tests, the Next.js production build, and Node runtime smoke checks with one TypeScript 7.0.2 installation. The current decision is to keep this single compiler boundary without TS 7 aliases or per-workspace compiler splits.