What is an Nx Go monorepo, and who should build one?

An Nx Go monorepo is a TypeScript Nx workspace where Go services are registered as first-class Nx projects. Each Go service gets a name, targets, and a place in the project graph, just like the Node apps beside it. The division of labor is strict. Go's own toolchain (go.mod, go.work, go build, go test) still compiles code and resolves modules. Nx handles only orchestration, caching, and affected-detection. Nx never needs to understand Go semantics. It only needs to know which files feed which task.

+--------------------------------------------------------+
|  Nx: task orchestration, cache, affected, project graph |
+---------------------------+----------------------------+
            |                              |
   Node toolchain (tsc, npm)      Go toolchain (go build/test)
            |                              |
  apps/web        (TS)          go.work --+-- apps/orders-api  (Go)
  apps/admin      (TS)                    +-- apps/billing-svc (Go)
  libs/api-client (TS)                    +-- libs/go-common   (Go)

This setup is meant for teams that already run Nx for TypeScript and are now adding Go services. Its value is consolidation:

  • You have one task runner.
  • You have one affected pipeline.
  • You have one way to declare that a TypeScript client depends on a Go API.

Without that last piece, the relationship lives only in someone's head or in a CI script.

It fits best when three conditions hold:

  • Shared CI: Go and TypeScript ship from the same pipeline.
  • Shared contracts: Go APIs publish schemas or generated types that TS clients consume, so a change on one side should trigger tests on the other.
  • Remote caching: Go builds and tests should benefit from the remote cache your TypeScript projects already use.

If your Go services share no contracts with your TypeScript code and deploy independently, a separate repository is usually simpler.

+------------------------------------------------------------------+
| Nx: task orchestration, cache, affected-detection, project graph |
|        (no Go semantics: only inputs -> tasks -> outputs)        |
+------------------------------------------------------------------+
              |                                     |
              v                                     v
+----------------------------+        +----------------------------+
| Node toolchain             |        | Go toolchain               |
| tsc, npm                   |        | go build, go test          |
| resolves package.json      |        | resolves go.mod, go.work   |
+----------------------------+        +----------------------------+
              |                                     |
              v                                     v
+----------------------------+        +----------------------------+
| apps/web             (TS)  |        | go.work                    |
| apps/admin           (TS)  |        |   |                        |
| libs/api-client      (TS)  | <----- |   +-> apps/orders-api  (Go) |
|                            |        |   +-> apps/billing-svc (Go) |
|                            |        |   +-> libs/go-common   (Go) |
+----------------------------+        +----------------------------+

<-----  Nx dependency edge: TS client depends on the Go API contract
go.work +->  links the local Go modules into one Go workspace

Nx sits above the Node and Go toolchains and only orchestrates, caches, and computes affected projects, while go.work links the Go modules and an Nx dependency edge ties the TypeScript client to the Go API it consumes.

Should each Go service have its own go.mod or share a root module?

The layout decision comes first because it determines what Nx treats as a project and what Go treats as a module.

Concern Per-service go.mod (services/api/go.mod) Single root go.mod
Dependency isolation Each service pins its own versions One version of every dependency for all services
Shared library drift Services can fall behind on libs/go/auth No drift; everyone uses the same commit
Upgrade coupling Bump one service at a time One bump touches every service
Nx project mapping One module per project directory, clean boundaries Projects are packages inside one module; go.mod changes affect all of them

Per-service modules suit teams that deploy and upgrade on separate schedules. A root module suits a small set of services that always ship together. The trade-off is upgrade coupling versus version drift.

With per-service modules, local imports need a way to resolve. Without help, each service needs replace directives that point at sibling paths. A workspace removes that need. Run go work init at the repository root, then go work use ./services/api ./services/worker ./libs/go/auth. The resulting go.work holds a go directive and a use block that lists those three directories. When you run a build anywhere under the root, the toolchain resolves the listed modules from disk.

Be careful about committing go.work. A committed workspace can hide a missing require or replace in a service's own go.mod. The monorepo build passes because the workspace supplies the local module. A Docker build that copies only services/api has no go.work, so it fails to resolve libs/go/auth. If you commit the file, add a CI step that builds each service with GOWORK=off. That step catches the gap before your image build does.

# Run from the repository root. Each listed directory already has its own go.mod.
go work init
go work use ./services/api ./services/worker ./libs/go/auth

cat go.work
# go 1.22
#
# use (
# 	./libs/go/auth
# 	./services/api
# 	./services/worker
# )
# (the go line matches your local toolchain version)

# With go.work present, builds under the root resolve libs/go/auth from disk.
go build ./services/api/... ./services/worker/...

# CI guard: build each service as if go.work did not exist, the same way
# a Docker build that copies only one service directory would see it.
# A missing require or replace in a service's go.mod fails here.
for svc in services/api services/worker; do
  echo "checking $svc without workspace"
  (cd "$svc" && GOWORK=off go build ./...) || exit 1
done

Creates a go.work for two services and a shared library, shows the resulting file, and adds a GOWORK=off CI loop that catches go.mod gaps the workspace would otherwise hide.

How do you register a Go service as an Nx project without a plugin?

…it reaches a release branch.

Without a plugin, a Go service becomes an Nx project once you add a project.json next to its go.mod, for example in services/api. Nx has no Go inference, so every target is declared by hand using the nx:run-commands executor. Set cwd to the service directory on each target. Nx runs commands from the workspace root by default, and the Go toolchain resolves the module from the current directory. If you leave out cwd, go build either fails to find a module or picks up the root go.work and builds a different set of packages than you meant.

Define three core targets:

  • build: runs go build -o with an output path. Declare that path in outputs so it can be cached later.
  • test: runs go test ./....
  • vet: runs go vet ./....

Then add a lint target. Its name should match the target your TypeScript projects use, so nx run-many -t lint covers both languages. It can run golangci-lint run if your team has standardized on that tool, or go vet together with a gofmt check if it hasn't.

gofmt -l exits with status zero even when it lists unformatted files. Wrap it so the target fails whenever the output is non-empty. Otherwise the lint target always passes.

Running go test ./... from the repository root does not do the same thing as nx run-many -t test. Depending on whether a root go.mod or go.work exists, it may error out or cover a different set of packages. It also bypasses the Nx cache and the affected-project calculation.

Document both entry points in the service README. Engineers who only know Go can cd into the service and use plain go commands. CI and cross-language work go through Nx.

{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "name": "api",
  "projectType": "application",
  "sourceRoot": "services/api",
  "tags": ["lang:go"],
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/services/api"],
      "options": {
        "cwd": "services/api",
        "command": "go build -o ../../dist/services/api/api ."
      }
    },
    "test": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "services/api",
        "command": "go test ./..."
      }
    },
    "vet": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "services/api",
        "command": "go vet ./..."
      }
    },
    "lint": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "services/api",
        "parallel": false,
        "commands": [
          "go vet ./...",
          "out=$(gofmt -l .); if [ -n \"$out\" ]; then echo \"$out\"; exit 1; fi"
        ]
      }
    }
  }
}

A hand-written services/api/project.json in which each nx:run-commands target sets cwd to the Go module directory, build declares its output path for caching, and the lint target runs go vet and fails if gofmt -l prints any files, because gofmt -l exits zero even when it finds unformatted code.

How do you make Nx caching correct for Go builds?

…can keep using nx targets. Whichever entry point they choose, the cache only stays trustworthy if the target's inputs describe everything the Go toolchain reads.

For a Go build target, the inputs should cover {projectRoot}/**/*.go, the project's go.mod and go.sum, and the workspace-root go.work (plus go.work.sum if you commit it). The outputs should point at the binary directory so a cache hit can restore the artifact. Omitting the module files produces false cache hits. If you edit a use or replace line in go.work, the build compiles different code, but no .go file in the project changed, so Nx replays a stale binary. Leaving out go.sum causes the same problem for dependency changes that appear only in the checksum file.

Two other cases slip past file globs:

  • //go:embed: Templates, SQL, or static assets pulled in this way need their own input patterns.
  • Environment-dependent settings: CGO_ENABLED, GOOS, GOARCH, and build tags change the output without changing any file, so declare them as env inputs.

Go already has its own build cache and caches passing test results. Locally, an Nx cache hit saves little time, and it adds "why didn't my test rerun?" confusion. The real gains come from skipping unaffected projects and from a remote cache, because a fresh CI runner starts with an empty Go cache.

Illustrative estimate. Assume 20 Go services, 6 minutes each for build and test, and a typical PR that affects 3 of them. A full run costs 120 runner-minutes. An affected-only run costs 18 runner-minutes.

// apps/api/project.json (Nx parses project.json as JSONC, so comments are allowed)
{
  "name": "api",
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "apps/api",
        "command": "go build -o ../../dist/apps/api/api ./cmd/api"
      },
      "cache": true,
      "inputs": [
        // Source code for this module
        "{projectRoot}/**/*.go",
        // Module files: dependency or checksum changes must invalidate the cache
        "{projectRoot}/go.mod",
        "{projectRoot}/go.sum",
        // Workspace files: use/replace edits change which code gets compiled
        "{workspaceRoot}/go.work",
        "{workspaceRoot}/go.work.sum",
        // Files pulled in via //go:embed are not .go files, so list them explicitly
        "{projectRoot}/internal/web/templates/**/*",
        "{projectRoot}/internal/db/migrations/*.sql",
        // Settings that change the binary without changing any file
        { "env": "CGO_ENABLED" },
        { "env": "GOOS" },
        { "env": "GOARCH" },
        // Build tags passed as GOFLAGS=-tags=...
        { "env": "GOFLAGS" }
      ],
      // A cache hit restores the binary from here
      "outputs": ["{workspaceRoot}/dist/apps/api"]
    }
  }
}

An Nx build target for a Go service whose inputs cover the Go sources, go.mod, go.sum, go.work, go.work.sum, embedded assets, and the environment variables that affect the output, with outputs pointing at the binary directory so a cache hit restores the artifact.

How does Nx know which Go and TypeScript projects depend on each other?

Nx builds its project graph from edges. Without a plugin, Nx has no idea that services/billing imports libs/go/auth, because it doesn't read Go source. The minimal fix is to declare implicitDependencies in the consuming project's project.json and list the projects it relies on by name. This works, but you are describing in configuration what the Go toolchain already knows from your imports.

The nx-go plugin closes that gap. It reads Go import paths and module requirements and turns them into graph edges, so adding an import updates the graph without any config change. In either case, check the result with nx graph before you rely on it. Open the affected service, confirm that each internal library it imports appears as a dependency, and confirm that nothing unexpected does.

Edges Nx never infers

Some dependencies cross the language boundary through a contract, not an import. For example, a TypeScript client might be generated from a Go service's OpenAPI spec or .proto files. No plugin connects these projects. Wire the edge yourself in one of two ways:

  • List the Go project in the client's implicitDependencies.
  • Give the client a codegen target whose dependsOn points at the producing project, and declare the contract files as inputs.

With either approach, a change to the contract makes nx affected rebuild and retest the client.

Hand-maintained edges drift. Services get renamed, specs move, and new consumers appear. A missing edge produces no error. nx affected skips the changed project, CI reports green, and the breakage first shows up in a later deploy. Treat these edges as correctness-critical. Require review of project.json changes alongside contract changes, and audit the graph periodically.

When should you adopt the nx-go plugin, and what are the alternatives?

Hand-written run-commands targets work, but every new Go service means copying a project.json, listing inputs, and declaring dependency edges by hand. The community nx-go plugin automates that layer. It provides generators that scaffold new Go projects and wire them into the workspace. It infers build, test, and lint targets so you don't have to declare them. It also adds graph edges by reading Go imports, so it can detect a dependency between Go projects that a reviewer missed. Generator names and options change between releases, so check the plugin's own documentation for current usage and for the Nx versions it supports.

The cost is ownership. Any Nx plugin has to track Nx's internal APIs. When a new Nx major version ships and the plugin hasn't caught up, you have two options: hold back Nx for the whole workspace, including every TypeScript project, or drop the plugin. A small Go footprint can end up setting the upgrade schedule for a much larger TypeScript codebase.

Option Setup effort Maintenance cost Graph accuracy Upgrade risk
Plain run-commands targets Moderate, per project Manual edits as services change Only as good as declared edges Low; uses core Nx only
nx-go plugin Low after install Low day to day; you depend on community maintainers High for Go-to-Go imports Can block Nx major upgrades
Go outside Nx, separate pipeline Low Two toolchains and two pipelines to maintain No cross-language graph None for Nx

Skip Nx for Go entirely if the repository is mostly Go, or if the team has no TypeScript projects. In those cases Go's own module and build tooling already handles dependency resolution and caching, and adding Nx gives you another toolchain to maintain without much benefit.

How do you run a polyglot Nx monorepo in CI?

In CI, install the Go toolchain and Node in the same job, before any Nx command runs. Nx only orchestrates. Each target still shells out to go or node, so a missing toolchain shows up as a failed target rather than a skipped one. Pin the Go version to match the go directive in your modules so local and CI builds agree.

Then run nx affected -t lint test build with base and head set to the merge base and the current commit. A single invocation covers both languages because Nx only sees targets, not languages.

Cache three directories separately: Go's module cache (go env GOMODCACHE), Go's build cache (go env GOCACHE), and Nx's local cache. They change at different rates. Module downloads change only when a go.sum changes, so key that cache on the hash of every go.sum. Go's build cache speeds up compiles even when Nx misses. The Nx cache skips the task entirely when it hits.

Add a job that builds each Go service with GOWORK=off. A go.work file can resolve a sibling module locally even when that module's go.mod lacks a correct require or replace. A standalone build fails on exactly the gaps that would break a release build or a Docker build of that service.

The setup costs engineering time in three places:

  • Writing accurate inputs for each target.
  • Keeping cross-language dependency edges current.
  • Updating the plugin whenever you upgrade Nx.

It saves time in three places:

  • Affected-only runs.
  • A remote cache shared across engineers and CI.
  • One lint/test/build command for every project.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx go monorepo, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.