How to Configure typescript-go for Specific Go Packages: ATA Setup Guide

TLDR: Configure the typeAcquisition object in your tsconfig.json to list specific Go packages in the include array, then run tsgo to automatically download the corresponding @types packages via the Automatic Type Acquisition (ATA) pipeline.

Microsoft's typescript-go brings the TypeScript compiler to Go, enabling type-checking against Go libraries through Automatic Type Acquisition (ATA). To configure typescript-go for specific Go packages, you define a typeAcquisition block in your tsconfig.json that tells the compiler exactly which Go import paths require type definitions.

Configuring the typeAcquisition Object

The ATA configuration resides in tsconfig.json (or jsconfig.json) under the typeAcquisition field. According to internal/tsoptions/declstypeacquisition.go, this object supports three key properties that control how the compiler resolves external types.

Including Specific Go Packages

Use the include array to specify exact Go package names whose typings should be fetched. When typeAcquisition.enable is set to true, the compiler invokes the ATA pipeline defined in internal/project/ata/ata.go to process these entries.

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2022"
  },
  "typeAcquisition": {
    "enable": true,
    "include": [
      "github.com/microsoft/typescript-go",
      "@myorg/mylib"
    ],
    "exclude": [
      "some-unwanted-package"
    ],
    "disableFilenameBasedTypeAcquisition": false
  }
}

Excluding Packages from ATA

The exclude array prevents specific packages from being installed even if filename heuristics would otherwise include them. This is processed during option parsing in internal/tsoptions/tsconfigparsing.go.

"typeAcquisition": {
  "enable": true,
  "include": ["github.com/example/foo"],
  "exclude": ["github.com/example/bar"]
}

Even though bar might be inferred from a file name, it will not be installed because it appears in exclude.

Controlling Filename-Based Heuristics

Set disableFilenameBasedTypeAcquisition to true to disable the default behavior where the compiler guesses package requirements based on source file names. This setting is declared in internal/tsoptions/declstypeacquisition.go.

Running the Compiler and Triggering ATA

After configuring your JSON file, invoke the compiler using the tsgo command. The entry point in cmd/tsgo/main.go calls execute.CommandLine from internal/execute/commandline.go, which parses the configuration and creates a core.ParsedOptions instance containing the *core.TypeAcquisition field.

When the Project constructor runs in internal/project/project.go, it checks typeAcquisition.Enable. If true, it calls ATA.Start, which eventually invokes installNpmPackages to run npm install @types/... for each included package.

npx tsgo

# or if installed globally:

tsgo

After the first run, verify that node_modules/@types/... folders exist for each listed package.

How Package Name Resolution Works

The ATA subsystem in internal/project/ata/ata.go converts Go package names to npm package names using helpers in internal/module/util.go. The function GetTypesPackageName transforms Go import paths into @types/<munged-name> format, while ParsePackageName handles the parsing logic. These utilities ensure that packages like github.com/microsoft/typescript-go map to the correct @types registry entries.

The resolution logic in internal/module/util.go then makes these downloaded types available to the LSP and type-checker automatically.

Summary

• Configure typeAcquisition in tsconfig.json to enable Automatic Type Acquisition for Go packages.
• Use the include array to specify exact Go package import paths requiring type definitions.
• Use the exclude array to block specific packages from being installed.
• Run tsgo to trigger the ATA pipeline, which downloads @types packages via installNpmPackages as implemented in internal/project/ata/ata.go.
• The compiler converts Go package names to npm names using GetTypesPackageName in internal/module/util.go.

Frequently Asked Questions

What configuration file does typescript-go use for ATA settings?

typescript-go reads Automatic Type Acquisition settings from the typeAcquisition object in your project's tsconfig.json or jsconfig.json. The schema for these options is defined in internal/tsoptions/declstypeacquisition.go, and the parsing logic resides in internal/tsoptions/tsconfigparsing.go.

How does typescript-go map Go package names to npm @types packages?

The compiler uses helper functions in internal/module/util.go, specifically GetTypesPackageName, to transform Go import paths into valid @types package names. The ATA implementation in internal/project/ata/ata.go then uses these mapped names when calling installNpmPackages to fetch the correct type definitions from the npm registry.

Can I disable automatic type acquisition completely?

Yes. Set typeAcquisition.enable to false in your configuration file, or omit the typeAcquisition object entirely. Additionally, setting disableFilenameBasedTypeAcquisition to true prevents the compiler from inferring package requirements based on your source file names, effectively limiting ATA to only explicitly listed packages.

Where are the type definitions installed when using typescript-go ATA?

The ATA pipeline installs packages into your local node_modules/@types/ directory via npm install commands triggered by the installNpmPackages function in internal/project/ata/ata.go. The TypeScript language service and compiler then resolve these typings automatically from that location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}