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

> Learn to configure typescript-go for specific Go packages by updating tsconfig.json. Automatically acquire Go types with ATA for tailored development.

- Repository: [Microsoft/typescript-go](https://github.com/microsoft/typescript-go)
- Tags: how-to-guide
- Published: 2026-04-25

---

**TLDR: Configure the `typeAcquisition` object in your [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) (or [`jsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/jsconfig.json)) under the `typeAcquisition` field. According to [`internal/tsoptions/declstypeacquisition.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/project/ata/ata.go) to process these entries.

```json
{
  "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`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/tsconfigparsing.go).

```json
"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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go) calls `execute.CommandLine` from [`internal/execute/commandline.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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.

```bash
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`](https://github.com/microsoft/typescript-go/blob/main/internal/project/ata/ata.go) converts Go package names to npm package names using helpers in [`internal/module/util.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/module/util.go) then makes these downloaded types available to the LSP and type-checker automatically.

## Summary

- Configure `typeAcquisition` in [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/project/ata/ata.go).
- The compiler converts Go package names to npm names using `GetTypesPackageName` in [`internal/module/util.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) or [`jsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/jsconfig.json). The schema for these options is defined in [`internal/tsoptions/declstypeacquisition.go`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/declstypeacquisition.go), and the parsing logic resides in [`internal/tsoptions/tsconfigparsing.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/project/ata/ata.go). The TypeScript language service and compiler then resolve these typings automatically from that location.