TypeScript 7.1 Beta: Migrating Tools That Use the Compiler API
tsc passes on the 7.1 beta, but your code generator that calls ts.createProgram() breaks. What changes for tools built on the compiler API?
- TypeScript 7.1 beta supplies a new compiler API, not a compatible replacement for the 6.x API.
- Tool authors need to choose new imports and manage the lifetime of compiler resources.
- Teams consuming a linter or framework integration still need support from that tool; a passing tsc command is insufficient evidence.
Existing Compiler API scripts need an integration change
If a tool imports the typescript namespace and calls ts.createProgram(), upgrading the dependency is not the whole migration. Microsoft's Compiler API wiki explicitly limits its examples to TypeScript 6.0 and earlier and warns that 7.1 uses a different API.
The October 20 beta introduces a programmatic interface for the native compiler. Its arrival matters especially to tools that inspect source, generate code or obtain type information.
Consider a project whose command-line type check passes while its code generator fails. Those can be separate compiler integrations. Changing application types is not a substitute for migrating the generator's API calls.
Choose synchronous or asynchronous access deliberately
The new entry points separate compiler calls from filesystem and syntax-tree utilities.
| Purpose | Import path |
|---|---|
| Synchronous compiler client | typescript/sync |
| Promise-based compiler client | typescript/async |
| Filesystem configuration | typescript/fs |
| AST types, guards and factories | typescript/ast, typescript/ast/is, typescript/ast/factory |
The official asynchronous implementation accepts root files and compiler options in createProgram and returns a Promise<Program>. A synchronous call site cannot treat that return value as an already available Program. Match the client to the tool's control flow before translating individual calls.
Resource disposal is part of the API contract
Microsoft warns that relying only on JavaScript garbage collection for API and Program objects can leave resources allocated on the Go side. For the synchronous API, use explicit disposal or using. For the asynchronous API, use await using or await the Promise returned by the cleanup method.
For synchronous resources, a using declaration ties disposal to scope exit. The resource’s Symbol.dispose method runs when the scope ends, including when an exception exits the block. Multiple declarations are disposed in reverse order, allowing a Program created after an API instance to be released first.
For a long-running tool, that means reviewing ownership as well as construction. A cache must not hand a disposed Program to a later request. Define when an analysis operation ends and which objects remain valid after it.
Separate code you own from integrations you consume
For an internal tool, inventory direct API calls and migrate their inputs, results and lifetimes. For a third-party tool, use its documented supported version and integration path.
- Find library calls such as
createProgramandtranspileModuleseparately from shell commands invoking the compiler. - Identify who loads configuration. The beta announcement's minimal compilation example takes explicit files and options; that sample does not discover a
tsconfig.jsonor implement--project. - Compare generated output and diagnostics in the actual workflow. Run code generation, linting and framework builds separately from a plain type check.
For tools still relying on the old interface, the 7.0 announcement describes side-by-side use of @typescript/typescript6, which provides the older API and a tsc6 executable. Package aliases may be needed when a dependency imports the name typescript directly.
The beta gives tool authors a path to the native compiler. Your project's migration is complete when its compiler-dependent workflows use a supported integration and produce the expected results.