Automatic Type Acquisition

The mechanism by which tsserver fetches @types/* packages on behalf of users so that JavaScript projects (or projects with vendored node_modules that lack types) still get IntelliSense.

Source

Path	Role
src/jsTyping/jsTyping.ts	discoverTypings — picks candidate package names from JS source and package.json
src/jsTyping/shared.ts	IPC message types between server and installer
src/typingsInstallerCore/typingsInstaller.ts	Cache management + npm orchestration
src/typingsInstaller/nodeTypingsInstaller.ts	Node-specific subclass that runs npm install
src/server/typingInstallerAdapter.ts	tsserver-side IPC client

Purpose

A user opens app.js containing const _ = require("lodash"). There's no @types/lodash installed. ATA:

1. Scans the file (and the project's package.json) for module names.
2. Filters those names against a published types-registry snapshot to confirm @types/<name> exists on npm.
3. Spawns the typingsInstaller child process and asks it to install the package.
4. The installer caches the result in ~/.cache/typescript/<version>/node_modules/@types/.
5. Once installed, tsserver re-resolves and the project picks up the new declarations.

ATA is on by default for inferred projects (loose .js files) and configured projects with typeAcquisition.enable: true. The typeAcquisition field in tsconfig.json/jsconfig.json configures include, exclude, and disableFilenameBasedTypeAcquisition.

Discovery

discoverTypings in src/jsTyping/jsTyping.ts takes:

• The list of files in the project.
• The project's package.json content (if any).
• A safe-list of "known package patterns" (e.g., lib/lodash.js → lodash, dist/foo.min.js → foo).
• An exclude-list and a typingsToExclude list.

It returns:

• cachedTypingPaths — already-cached typings that the project can use immediately.
• newTypingNames — packages to install.
• filesToWatch — paths the server should watch to know when to re-discover.

Installation

src/typingsInstallerCore/typingsInstaller.ts is the host-agnostic installer. It:

• Loads the types-registry JSON file (a manifest of every @types/* package and its TypeScript-version compatibility).
• For each requested package, resolves the right @types/<package> version against the registry and the user's running TypeScript version.
• Writes a request to its concrete subclass (NodeTypingsInstaller) which runs npm install in the cache directory.
• Reports progress via BeginInstallTypes, EndInstallTypes, InvalidateCachedTypings events.

Recent commits (April 2026) hardened the package-name validation in InstallPackageRequest to defend against malformed requests:

• f1a9288c — "Also check package name validity in InstallPackageRequest"
• c7a0ae10 — "Harden ATA package name filtering"

The validation now lives on both sides of the IPC boundary.

How it works

sequenceDiagram
    participant Editor
    participant tsserver
    participant Adapter as TypingsInstallerAdapter
    participant TI as typingsInstaller (child)
    participant npm

    Editor->>tsserver: open app.js
    tsserver->>tsserver: jsTyping.discoverTypings
    tsserver->>Adapter: requestInstallTypings(["lodash"])
    Adapter->>TI: { kind: "discover", projectName, files }
    TI->>TI: filter against types-registry
    TI->>npm: npm install @types/lodash
    npm-->>TI: install OK
    TI->>Adapter: { kind: "set", typings }
    Adapter->>tsserver: invalidate cached resolutions
    tsserver->>Editor: refreshed completions

Caching

Typings live under ~/.cache/typescript/<typescript-version>/node_modules/@types/<pkg>/. The cache is keyed on TypeScript version because @types/* packages declare TypeScript-version compatibility — different tsserver versions use different cache subdirectories.

Disabling ATA

Users opt out via typeAcquisition.enable: false in tsconfig.json/jsconfig.json, or via the --disableAutomaticTypingAcquisition tsserver flag.

Integration points

• Triggered by tsserver's ProjectService when a project's files change.
• Reads package.json to know what dependencies the user already has.
• Writes declaration files into a per-user cache that the project's compiler host then reads as if they were on disk.
• Reports progress events back to the editor via tsserver's standard event stream.

Entry points for modification

• Discovery rules — src/jsTyping/jsTyping.ts.
• IPC contract — src/jsTyping/shared.ts.
• npm-driven install behaviour — src/typingsInstaller/nodeTypingsInstaller.ts.
• tsserver-side adapter — src/server/typingInstallerAdapter.ts.

See apps/typings-installer for the executable, and apps/tsserver for the surrounding host.