Create your first Go project

import { Steps } from ‘@astrojs/starlight/components’;

In this tutorial we’ll create a Go application with Nx, then run, test, and build it using targets that gonx infers from go.mod. Along the way we’ll see how Nx caching and the project graph work with Go projects.

Before we start

We need:

• Node.js 20+ and an Nx 23.x workspace
• Go — a stable release (1.18+ for multi-module workspaces)

gonx 3.x targets Nx 23.x:

Nx version	gonx version
23.x	3.x

Note

gonx is a fork of @nx-go/nx-go, modernized for Nx 23 with inferred tasks and a tree-sitter-based project graph.

Steps

1. **Create a workspace with the gonx preset**

We’ll start by creating a fresh Nx workspace with gonx pre-configured:

npx create-nx-workspace go-workspace --preset=@naxodev/gonx

This scaffolds an Nx workspace with gonx registered in nx.json and a starter Go project. If you already have a workspace, install gonx into it instead:

npx nx add @naxodev/gonx

See install gonx for details.

2. Create a Go application

   Now we’ll generate a Go application:

   cd go-workspace
   npx nx g @naxodev/gonx:application my-go-app

   The generator creates a Go project with a package main entry point and a go.mod file. gonx detects the go.mod and automatically infers build, serve, test, lint, tidy, and generate targets — no project.json needed. We can pass --template to choose standard, cli, or tui. See the application generator guide for all options.

3. Run the application

   Let’s run it:

   npx nx serve my-go-app

   The serve target runs go run from the project root. It’s a continuous target, so it stays running until we stop it. See the serve executor guide.

4. Test the project

   We can run the project’s tests with:

   npx nx test my-go-app

   The test target runs go test ./.... Because the target is cached, running it again with no source changes will return instantly from the Nx cache. See the test executor guide.

5. Build the project

   Finally, let’s build an executable:

   npx nx build my-go-app

   The build target compiles a binary and outputs it to dist/<projectRoot>/. See the build executor guide.

Verify

Let’s confirm Nx detected our project and inferred the right targets:

npx nx show projects
npx nx show project my-go-app

nx show project lists the build, serve, test, lint, tidy, and generate targets — all inferred, with no project.json file. Run npx nx build my-go-app a second time to see Nx caching in action: the second run is served from the cache and completes almost instantly.

Explore the project graph

gonx builds the Nx project graph by parsing Go imports with tree-sitter. Let’s visualize the dependencies:

npx nx graph

This opens the Nx project graph UI in your browser. If we add a library and import it from our application, the graph will show the dependency edge — even without go.work. See how static analysis works to learn how gonx resolves imports to Nx projects.

Next steps

• Application generator — all options including templates and tags
• Library generator — scaffold a reusable Go package
• Plugin options — customize target names and tags
• How static analysis works — the tree-sitter project graph
• Migrate to gonx 3.0.0 — coming from nx-go