# gots

> Generate TypeScript types from Go source code with cross-package type resolution. Use when you need to sync Go struct definitions to TypeScript interfaces, convert Go const blocks to TypeScript union types, or maintain type safety between Go backends and TypeScript frontends.

- Author: niwoerner
- Repository: niwoerner/gots
- Version: 20251221120256
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/niwoerner/gots
- Web: https://mule.run/skillshub/@@niwoerner/gots~gots:20251221120256

---

---
name: gots
description: Generate TypeScript types from Go source code with cross-package type resolution. Use when you need to sync Go struct definitions to TypeScript interfaces, convert Go const blocks to TypeScript union types, or maintain type safety between Go backends and TypeScript frontends.
license: MIT
compatibility: Requires Go 1.21+ with golang.org/x/tools/go/packages
metadata:
  author: niwoerner
  version: "1.0"
---

## When to Use

Use gots when:
- You have Go structs that need TypeScript equivalents
- You need cross-package type resolution (e.g., `types.Status` in another package)
- You want Go const blocks converted to TypeScript union types
- You need to maintain type sync between Go backend and TypeScript frontend

## Installation

```bash
go install github.com/niwoerner/gots/cmd/gots@latest
```

## Configuration

Create `gots.yaml` in your Go module root:

```yaml
packages:
  - path: "github.com/yourorg/project/types"
    output_path: "../ui/src/types/generated.ts"
  - path: "github.com/yourorg/project/api"
    output_path: "../ui/src/types/generated.ts"
    type_mappings:
      "map[string]any": "Record<string, unknown>"
```

### Config Options

| Option | Required | Description |
|--------|----------|-------------|
| `path` | Yes | Go package import path |
| `output_path` | Yes | Output TypeScript file path (relative to config) |
| `include_files` | No | Only process these Go files |
| `exclude_files` | No | Skip these Go files |
| `type_mappings` | No | Custom Go → TypeScript type mappings |

## Usage

```bash
# Run from directory containing gots.yaml
gots

# Or specify config path
gots --config path/to/gots.yaml
```

## Type Conversion Rules

| Go | TypeScript |
|----|------------|
| `string` | `string` |
| `int`, `int64`, etc | `number` |
| `float32`, `float64` | `number` |
| `bool` | `boolean` |
| `[]T` | `T[]` |
| `map[K]V` | `{ [key: K]: V }` |
| `*T` | `T \| null` |
| `any`, `interface{}` | `unknown` |
| Struct | `interface` |
| Const block | Union type |

## Examples

### Cross-Package Types

```go
// types/types.go
type Status string
const (
    Active   Status = "active"
    Inactive Status = "inactive"
)

// api/response.go
type Response struct {
    Status types.Status `json:"status"`
}
```

Generated TypeScript:

```typescript
export type Status = "active" | "inactive";

export interface Response {
    status: Status;  // Properly resolved, not "any"
}
```

### Custom Type Mappings

```yaml
type_mappings:
  "map[string]any": "Record<string, unknown>"
  "time.Time": "string"
  "uuid.UUID": "string"
```

## Output Merging

Multiple packages can output to the same file:

```yaml
packages:
  - path: "project/types"
    output_path: "generated.ts"
  - path: "project/api"
    output_path: "generated.ts"  # Same file = merged output
```

## Troubleshooting

### Package not found
Ensure you run gots from a directory with a `go.mod` file, or the packages are accessible via `GOPATH`.

### Types show as `unknown`
The type may not be exported (must start with uppercase) or the package containing it isn't listed in config.

### Enum not generating as union
Const blocks must have an explicit type and string values:
```go
type Status string  // Required: explicit type
const Active Status = "active"  // Required: string value
```