[RFC] Native Go support

[anthonyshew]

Turborepo now experimentally supports Go: https://turborepo.dev/docs/guides/tools/go

Motivation

One of the longest-standing, open requests in Turborepo is to support more language toolchains than JavaScript: #683

This RFC introduces Go as a natively supported language in Turborepo, using Go’s built-in module and workspace tooling.

What drives this ask?

Monorepos can be large, and don’t have to contain just one language. It is common to run a monorepo with many languages and language toolchains in it. However, this comes with the complexity of managing workflows across all of these toolchains. Each language creates its own partition within the monorepo, and it becomes complicated to manage the interactions between each language’s domain.

Turborepo users see what Turborepo offers for simplifying their JavaScript/TypeScript workflows, and want the same for all languages in their repository. The canonical ask becomes “How do I make turbo run lint run all the linters for all my languages?”

Without native support, taking Turborepo across toolchains meant porting conventions of JavaScript toolchains onto your other languages. You’d have to put a package.json into your Go modules for Turborepo to add them to your Package Graph, for example. A more verbose description of this approach can be found in our multi-language support documentation.

With this new experimental support, those JavaScript wrappers are no longer necessary for Go workspaces. Turborepo discovers modules from a repository-root go.work, reads their module dependencies, and adds them to the same Package Graph as your JavaScript/TypeScript packages.

Why Go?

Go is a natural next step in expanding Turborepo’s native language support beyond JavaScript/TypeScript and Rust.

A repository might contain a TypeScript frontend, Go services, and shared Go libraries. These projects use different toolchains, but developers still need a consistent way to build, test, and check their work.

Go already provides module management, workspaces, and standard commands for common tasks. Turborepo can build on those conventions rather than asking users to recreate them through JavaScript tooling.

The goal is not to replace Go’s tooling. It is to make Go projects participate naturally in repository-wide workflows.

What about standalone Go workspaces?

Standalone Go workspaces are supported, too. A repository does not need JavaScript application code to benefit from native Go workspace support.

Go already has strong build and test caching. Turborepo should complement those capabilities, not replace them. Its value is in coordinating tasks across modules, selecting affected modules and their dependents, and sharing cacheable task results across developer and CI machines.

Go’s internal build and module caches remain Go’s responsibility.

Enabling for your Turborepo

1 . Install a Turborepo release that includes experimental Go workspace support.
2. Make Go 1.22 or newer available as go on your PATH.
3. Add a go.work at the repository root if you do not have one already, with use directives identifying your Go modules. Each member must have a go.mod with a module path.
4. Enable the feature using its Future Flag in turbo.json:

  {
    "futureFlags": {
      "experimentalGoWorkspaces": true
    }
  }

For more information on getting started, please see the Go guide.

Usage

Using Turborepo for Go should feel familiar to using it for JavaScript/TypeScript.

• Run turbo run build to build your Go modules. Modules with exactly one runnable main package produce a binary in dist/.
• Run turbo run test to run go test ./... in your modules.
• Run turbo run lint to run go vet ./....
• Run turbo run format to run go fmt ./....
• Run turbo run dev to run modules with exactly one runnable main package.

You can also filter tasks using a module’s path:

  turbo run test --filter=example.com/acme/api

To learn more about built-in tasks, command overrides, caching, and
workspace-wide execution, please see the Go guide.

What feedback is the Turborepo team looking for?

In short, everything. We want to hear about:

• UX improvements
• Your experience in a standalone Go workspace
• Your experience in a mixed-language repository, such as a TypeScript frontend with Go services
• Whether the built-in tasks match your Go workflows
• Caching concerns, including cross-compilation and CGO
• Anything else?

[Stanzilla]

First impression: nice!

One thing I need to figure out first before I can adopt it more widely for testing is that I now need a Docker image that has both node and go installed for all steps since Turbo will always need both.

Second thought: A migration/best practice guide/skill would be nice, like currently I have dummy package.jsons everywhere. What should we do instead/with makefiles?

[Stanzilla]

I can check tomorrow, it did not think of deleting the package.jsons on its own though, the docs dont mention that you no longer need them

[Stanzilla]

Okay deleted the package.jsons, small downside, I can no obviously no longer do filters with the npm scope prefix which makes it a little uglier but oh well.

[anthonyshew]

Hmmm, this is a constraint of the Golang ecosystem. Modules are identified by their path name...

I think I can make this a little better by taking the last component of the module path as the name. There's some precedence for this in go tool.

There isn't a way for me to let you preserve that name outright as @tds/backend, but you would be able to use backend or tds-backend. The fact that / is a path separator means that @tds/backend by necessity has to get split into @tds and backend path components. But, still, inferring from the last path component as a name is an improvement.

#14086 changes names to be more convenient. This is a breaking change so please be mindful!

[anthonyshew]

v2.10.14-canary.4 has that rename, so that'll be a breaking change for you.

[anthonyshew]

One thing I need to figure out first before I can adopt it more widely for testing is that I now need a Docker image that has both node and go installed for all steps since Turbo will always need both.

Solved! Standalone binary installation is now available: https://turborepo.dev/docs/getting-started/installation#global-installation

[PunGrumpy]

Tried this on a mixed npm and go.work repo: I deleted the package.json wrappers off both Go modules, and build, test and lint came back green locally with no other changes. Great first cut. Filed one bug separately for a Go task hash that changes with the invoked task (hash_issue_number_here). The rest belongs here.

Enabling the flag makes the toolchain a hard requirement for every run

Any turbo run in the repo shells out to go work edit -json while building the package graph, before it reads --filter:

$ env PATH=/path/without/go turbo run build --filter=web
  x Go is required for experimental Go workspaces, but `go` was not found
  | while running `go work edit -json`. Install Go 1.22 or newer and ensure
  | `go` is on PATH.

web is a Next.js app that shares no code with either Go module. Our Vercel deployment for it failed on this line, because the Node build image carries no Go toolchain.

Nothing inside Turborepo opts out. --filter is read too late, and no environment variable disables the discovery. That left two ways out: install Go into a Node build image so it can run next build, or stop invoking Turborepo from the deployment. We took the second, so the flag cost us Turborepo on the deploy path, which is where its remote cache paid off most.

This reads like a property of all three language flags. experimentalCargoWorkspaces shells out to cargo metadata and experimentalPythonWorkspaces to uv workspace metadata --frozen. I reproduced only the Go case, so treat the other two as a reading of the error strings rather than a tested claim.

Reading go.work only once a Go package lands in the run's scope would fix it. Failing that, a documented opt-out, or degrading to a warning that drops the Go packages from the graph, would let a JavaScript-only filter keep building.

The synthesized format task can't run

go fmt ./apps/api/... ./packages/core/... fails from a workspace root:

pattern ./apps/api/...: directory prefix apps/api does not contain main module or its selected dependencies

go fmt rejects cross-module patterns in workspace mode, unlike go vet and go test, which both accept them. Either gofmt -l -w or a per-module go fmt ./... would work. The workaround, through experimentalTaskCommand:

"format": { "command": { "go": ["gofmt", "-l", "-w", "."] } }

--filter changes the shape of the graph

Unfiltered, turbo run test runs only go-workspace#test. With --filter=./packages/core, a per-module packages/core#test running go test ./... appears instead. Each makes sense alone, but they hash differently, so the two invocations never share a cache entry. That bites when you filter locally and run unfiltered in CI.

Default inputs cover the whole module directory

Touching apps/api/Dockerfile or packages/core/CHANGELOG.md changes the hash of go-workspace#test. Because test and lint exist only at workspace level, one unrelated file re-runs every Go test in the repo.

A default of **/*.go plus go.{mod,sum} would narrow it, though //go:embed makes that unsafe in general. Synthesizing per-module test and lint tasks by default would at least hold a miss to one module. The escape hatch already works: a package turbo.json with "inputs": ["$TURBO_DEFAULT$", "!Dockerfile"] keeps the inferred cross-module inputs.

A leftover package.json silently double-builds

Before I deleted the wrappers, both @pigo/api and the Go module sat in scope, each with a working build, so go build ran twice and nothing warned. A warning when a go.work member also resolves as a package-manager workspace package would save the next person that.

Task names are fixed

Our scripts are check and fix, not lint and format, so adopting this meant renaming them. No complaint, but the per-toolchain command map deserves documenting as the intended escape hatch. It isn't in the published skill reference yet; I found it by reading strings in the binary.

The synthesized -o path is worth documenting

Our Go app built to bin/pigo-api, which our host's Go builder located on its own. The synthesized go build -o dist/api . it could not find, and the deploy failed with No compiled Go binary found after buildCommand. Not a bug, but the -o path silently replaces a contract the repo may already have with whatever consumes the binary. Honoring the repo's existing outputs globs, or naming the path in the docs, would catch that before a deploy does.

What already works well:

• The hint when go.work is present and the flag is off
• Dependency edges derived from the go.mod require
• Go's env vars, CGO_ENABLED, GOARCH, GOOS and the rest, added to the task env automatically
• Directory filters such as --filter=./apps/api, so the full module path stays optional
• Preflight errors for a vendor directory, a non-member module, and a duplicate module path, each of which named its fix

[anthonyshew]

Will work my way through all of this, thank you!

[PunGrumpy]

thank you for your hard work👍

[anthonyshew]

v2.10.14-canary.2 ships fixes for all of these. Thank you again!