TypeScript 7.1 Beta Brings Import Attributes and Source Phase Imports

What happened

Microsoft announced TypeScript 7.1 in beta, introducing several features aligned with emerging ECMAScript proposals. The release adds language-level support for import attributes in ambient module declarations, source phase imports for modules like WebAssembly, and stabilizes ES2026 as a compilation target. Additionally, TypeScript 7.1 includes a new modular API designed for building tools that need to perform compilation and analysis tasks.

npm install -D typescript@beta

Import Attributes in Ambient Modules

Import attributes are metadata attached to import statements that instruct runtimes and bundlers how to interpret imported content. TypeScript 7.1 now allows these attributes to be specified directly in ambient module declarations using wildcard patterns combined with an attribute constraint. For example, you can declare that any CSS file imported with type: "css" returns a CSSStyleSheet, or that any text file imported with type: "text" returns a string. This ensures developers receive type errors when they forget the required import attribute and prevents type mismatches between the import statement and the module's actual exports.

Previously, developers had to write separate ambient module declarations for each file pattern (*.css, *.txt, *.md) without any way to enforce that the correct import attribute was used. With TypeScript 7.1, a single declaration can specify both the file pattern and the required attribute, eliminating redundancy. The feature also handles cases where runtime behavior differs based on the presence of attributes—for instance, bundlers might treat CSS files as CSS Modules by default, but specifying type: "css" in the import can override this and ensure the file is imported as a CSSStyleSheet object.

TypeScript does not validate these declarations against files on disk; failed lookups will be reported at runtime or during a bundler's build process. Additionally, these declarations are not included in TypeScript's built-in type libraries, and library authors are advised not to publish them in their packages. End users should declare them in their own projects to maintain flexibility based on their environment configuration.

declare module "*" with { type: "css" } {
  const content: CSSStyleSheet;
  export default content;
}

Source Phase Imports for WebAssembly

Source phase imports introduce a new ECMAScript proposal feature that allows importing modules in a partially initialized state. When using import source, the runtime returns an AbstractModuleSource object representing the module after parsing and analysis but before its imports are loaded and linked. This is particularly valuable for WebAssembly, where the object becomes a WebAssembly.Module instance that can be passed directly to WebAssembly.instantiate.

This approach enables fine-grained control over module instantiation. For example, developers can import a WebAssembly module, configure its imports (such as WASI environment settings), and then instantiate it with those specific configurations. Source imports retain identity across imports, meaning the same source module imported multiple times or via dynamic import will return the same object, allowing reliable comparisons and use in Maps and Sets.

Source imports can also be performed dynamically using the import.source meta-property function. For JavaScript modules, source imports are currently limited in utility as the platform has not yet stabilized mechanisms to customize their behavior, but future ECMAScript features are expected to enable similar instantiation patterns for JavaScript as exist for WebAssembly. Developers must use appropriate --module settings (esnext, nodenext, or preserve) and include esnext in --lib or --target to access this feature.

import source SuperFastThing from "./super-fast-thing.wasm";
const fastThingInstance = await WebAssembly.instantiate(SuperFastThing, {
  wasi_snapshot_preview1: wasi.wasiImport
});

ES2026 Stabilization and New Library Methods

TypeScript 7.1 now supports es2026 as a stable --target and --lib option. Several proposed features have stabilized in the ES2026 specification, including Math.sumPrecise(), Iterator.concat(), Iterator methods like zip and zipKeyed, JSON.rawJSON(), Map and WeakMap getOrInsert and getOrInsertComputed methods, and Uint8Array encoding methods (toBase64, setFromBase64, toHex, setFromHex, fromHex, fromBase64). The lib.esnext option also includes a few additional proposed methods: Promise.allKeyed, Promise.allSettledKeyed, and Iterator.prototype.chunks, join, and includes.

These additions reflect the maturation of features that were previously available only in lib.esnext. Developers targeting ES2026 environments can now use these APIs with full type safety.

New Modular TypeScript 7.1 API

TypeScript 7.1 introduces a redesigned API for building tools that need to compile and analyze TypeScript code. Instead of exposing a single monolithic API, the new design provides multiple entry points, each serving a specific purpose: typescript/sync for synchronous compilation, typescript/async for Promise-based operations, typescript/fs for filesystem abstractions, typescript/ast for syntax tree types and utilities, and typescript/ast/factory for node creation functions.

The new API manages resources through the Disposable pattern. Both API instances and Program instances must be explicitly disposed or declared with the using keyword to prevent memory leaks on the Go runtime side. Developers can manually dispose of them with api.close(), program.dispose(), or api[Symbol.dispose](), or rely on the using keyword to automatically dispose when objects go out of scope.

A key feature of the API is support for snapshots, which represent a version of all projects and programs at a point in time. Rather than rebuilding the entire compilation from scratch after changes, developers can create a new snapshot derived from a prior one using snapshot.update(), which often saves significant work. This is particularly valuable for tools like language servers that respond to incremental file changes during editing.

import { API } from "typescript/sync";
using api = new API();
using program = api.createProgram(fileNames, options);
const diagnostics = program.getSemanticDiagnostics();
const emitResult = program.emit();

What to do

To test TypeScript 7.1, install the beta version using npm install -D typescript@beta. If you use ambient module declarations with file patterns, consider updating them to specify import attributes where your code or bundler requires them. For projects targeting Node.js or browsers that support source phase imports and WebAssembly, experiment with the new import source syntax to see if it simplifies module instantiation workflows. If you build tools that compile or analyze TypeScript code, review the new modular API documentation to see whether the snapshot-based incremental compilation approach would improve performance in your use case.

Source

AI-assisted, verified against the source. This post was drafted with AI from the primary source linked above and checked automatically against it. For anything you depend on, read the original.