TypeScript 7.1 Beta: New API, es2026 and What Can Break

TypeScript 7.1 is in beta. The official announcement is dated October 20, 2026, and its headline change is that the native compiler gets a programmatic API again, the thing TypeScript 7.0 shipped without. This guide covers what is in the beta, Microsoft's own benchmarks, and the two changes that can add errors. For the 7.0 baseline and my own measurements, see my TypeScript 7 upgrade guide.

How do I install the TypeScript 7.1 beta?#

npm install -D typescript@beta

pnpm add -D typescript@beta

yarn add -D typescript@beta

bun add -d typescript@beta

typescript@latest is still the 7.0 line, so removing the beta is a matter of reinstalling typescript@latest. Try it on a branch first, and run your CI type-check against it before trusting it.

What is the new TypeScript 7.1 API?#

It is not the old single ts object. The beta exposes focused entry points:

A few details matter if you build tooling on it. API and Program objects are Disposable, so dispose them manually or declare them with using, and a disposed program cannot be reused. Snapshots (api.createSnapshot and snapshot.update()) model changes over time. The API does not discover tsconfig.json and does not support --project, and the post says more examples are coming.

What are content mappers?#

Content mappers let non-.ts files, such as Vue or Svelte single-file components, be type-checked by the native compiler. You register them per file extension in tsconfig.json under contentMappers, with package, extensions and options fields.

Because a mapper runs external code, you must pass the --runExternalCode flag. In VS Code they need workspace trust and mapper permissions, and the js/ts.contentMappers.enabled setting can switch them off. According to the announcement, mappers are implemented in pull requests for Vue and Svelte, and prototyped or implemented for Astro, CSS Modules, Ember and MDX. The example @vue/content-mapper package is not on npm yet, so this is early.

What else is new?#

• es2026. --target es2026 and --lib es2026 are stable. The lib additions include Math.sumPrecise(), Iterator.concat(), JSON.rawJSON(), Error.isError(), Array.fromAsync() and several Map, WeakMap and Uint8Array methods.
• esnext additions. --lib esnext adds Promise.allKeyed, Promise.allSettledKeyed, Iterator.zip, Iterator.zipKeyed, Iterator.prototype.chunks, Iterator.prototype.join and Iterator.prototype.includes.
• Import attributes in ambient modules. You can declare declare module "*" with { type: "css" } (also "text" and "bytes"). Missing attributes produce errors, matches are not checked against disk, and libraries should not ship these declarations.
• Source phase imports. import source is described as an ECMAScript proposal. It needs --module set to esnext, nodenext or preserve, plus the esnext lib or target. Imported modules are typed AbstractModuleSource, and WebAssembly source imports yield WebAssembly.Module.

How much faster is TypeScript 7.1? (Microsoft's numbers)#

These are from the announcement, using the default 4 checker threads and --noEmit:

The gains vary a lot by codebase, so measure your own project instead of assuming 1.9x.

What can break in TypeScript 7.1?#

The announcement lists two behavior changes that can add errors to a build that passes today:

1. Updated DOM types in lib.d.ts. Regenerated DOM types can affect type checking. The post links the tracking issue (microsoft/TypeScript #63702) and does not list specific changes, so run a full type check and read the diff of errors.
2. Stricter distributive conditional types. A type parameter inside a distributed branch is no longer treated as related to the original. The example error reads: "'B' is only assignable to the non-distributed 'A', but 'A' has been distributed here." Fixes usually mean removing an unnecessary constraint or adding a conditional check. See issue #63708.

Does typescript-eslint support TypeScript 7.1?#

The announcement does not mention typescript-eslint. The missing API was the blocker, and it is now in beta, but typescript-eslint has its own integration work. Check typescript-eslint issue 10940 for its current state. Until a release says it supports TypeScript 7, keep the side-by-side setup from my guide to the typescript-eslint does not support TS 7.0 error.

When will TypeScript 7.1 be stable?#

The announcement says a release candidate is expected about a month after the beta, with the final release shortly after. The earlier iteration plan listed different dates, and the beta itself slipped from the plan, so treat any specific date as a target.

Key takeaways#

• Install the beta with npm install -D typescript@beta, and test on a branch first.
• The new API is a set of entry points (typescript/sync, typescript/async, typescript/fs, typescript/ast), not the old ts object.
• Content mappers need --runExternalCode and are still early for Vue and Svelte.
• es2026 is stable, and ambient modules can use import attributes.
• Microsoft reports 1.2x to 1.9x faster checking than 7.0, and your own results will differ.
• Watch for new errors from DOM types and distributive conditional types.