Go Extension

The @putnami/go extension provides build, test, lint, and serve jobs for Go projects in a Putnami workspace.

Scope: All jobs are project-only. They require a project context (no workspace-level runs).

Go version management

The extension resolves the Go toolchain automatically:

1. System PATH: if Go is already installed on your system, it is used directly.
2. Managed download: if no system Go is found, reads the go directive from the workspace go.work file and downloads it to .putnami/extensions/@putnami-go/libs/go-{version}/.
3. Fallback: if no go.work exists and no system Go is found, fetches the latest stable version from go.dev.

You can pass an explicit version to override go.work resolution (e.g. from a job parameter).

External tools

• Go (auto-managed, see above)
• golangci-lint
• staticcheck

Enable the extension

Install the package at the workspace root:

bun add @putnami/go

{
  "name": "my-workspace",
  "devDependencies": {
    "@putnami/go": "latest"
  }
}

Jobs

build

Compile Go packages/binaries with cross-compilation support.

Behavior:

• Optionally refreshes dependencies (go.mod and package.json sync) unless --skip-deps.
• Supports cross-compilation via --target <os/arch>.
• Writes build output to the job output directory (or --output).

Options (selected):

• --target / -t <os/arch> (e.g., linux/amd64)
• --output / -o <path>
• --skip-deps
• --readonly, --mod <readonly|vendor|mod>
• --ldflags, --gcflags, --asmflags, --tags
• --race, --trimpath, --buildmode, --cgo

Example:

bunx putnami build . --target linux/amd64

test

Run Go tests with JSON output and optional coverage.

Behavior:

• Detects Go projects via go.mod.
• Runs go test -json and parses structured output.
• Can generate coverage profile and HTML report.

Options (selected):

• --coverage (also generates HTML)
• --race
• --timeout <duration>
• --run <pattern>, --count <n>, --shuffle
• --bench <pattern>, --benchtime <duration>
• --parallel <n>, --failfast
• --coverprofile <file>, --covermode <set|count|atomic>
• --outputdir <dir>

Example:

bunx putnami test . --coverage

lint

Run golangci-lint and/or staticcheck.

Behavior:

• Defaults to --tool all (runs both).
• golangci-lint supports --fix and config discovery.

Options:

• --tool <golangci-lint|staticcheck|all>
• --fix (golangci-lint only, default: true)
• --config <path>
• --new, --out-format <format>, --sort-results, --timeout <duration>

Example:

bunx putnami lint . --tool golangci-lint

Config resolution (golangci-lint):

1. --config
2. Project .golangci.yml/.golangci.yaml
3. Workspace .golangci.yml/.golangci.yaml
4. Default config from @putnami/go

serve

Run Go applications as servers.

Behavior:

• Development mode (default): go run . with file watching and restart.
• Production mode (NODE_ENV=production or --watch false): runs the built binary.

Options:

• --watch <boolean> (default: true)
• --port <number> (sets PORT env)
• --killPort
• --args <string>

Example:

bunx putnami serve . --port 8080

Go version resolution

The extension resolves the Go binary in this order:

1. System PATH — If go is already installed on your system (Homebrew, apt, manual install), it is used as-is. GOROOT and PATH are inherited from the environment — the extension does not override them.
2. Managed download — If no system Go is found, the extension downloads the version specified in the workspace go.work file (auto-generated by syncGoWork() before every job) into .putnami/extensions/@putnami-go/libs/go-{version}/. Multiple versions can coexist. For managed installs, GOROOT and PATH are computed from the download path.
3. Latest stable — If no go.work exists and no system Go is found, fetches the latest stable version from go.dev.

In both cases, GOCACHE and GOMODCACHE are shared under .putnami/extensions/@putnami-go/cache/ so that compiled packages are reused across all Go projects.

Caching and dependencies

• build depends on ^build and tracks: **/*.go, go.mod, go.sum, go.work, package.json.
• test tracks: **/*.go, go.mod, go.sum, go.work, package.json.
• lint tracks: **/*.go, go.mod, go.work, .golangci.yml, .golangci.yaml, package.json.
• serve depends on build and is never cached.

Project Templates

The Go extension ships two project templates for quick scaffolding:

go-server

An HTTP server using net/http with a JSON health endpoint.

putnami projects create my-api --template go-server

Generates:

packages/my-api/
├── package.json          # @putnami/go dev dependency, serve/build/test/lint scripts
├── go.mod                # Go 1.23 module
├── main.go               # HTTP server on port 3000, JSON { Hello: "World" }
└── main_test.go          # Handler test

Run immediately:

putnami serve my-api

go-library

A minimal Go library with an exported function and test.

putnami projects create my-lib --template go-library

Generates:

packages/my-lib/
├── package.json          # @putnami/go dev dependency, build/test/lint scripts
├── go.mod                # Go 1.23 module
├── hello.go              # Hello(name) function
└── hello_test.go         # Unit test

Examples

# Build a package
bunx putnami build .

# Cross-compile for Linux
bunx putnami build . --target linux/amd64

# Run tests with coverage
bunx putnami test . --coverage

# Lint with golangci-lint only
bunx putnami lint . --tool golangci-lint

# Serve on port 8080
bunx putnami serve . --port 8080

Notes

• Go and lint tools (golangci-lint, staticcheck) are downloaded automatically on first use.
• Downloaded toolchains are stored in .putnami/extensions/@putnami-go/ (add to .gitignore).

Next steps

• Previous: TypeScript
• Next: Python