Migration from nx-go

This guide helps you migrate from the original @nx-go/nx-go plugin to GoNx.

Caution

Although GoNx works well as a drop-in replacement for nx-go in most cases, our philosophy and core implementation have changed since the first fork, which may cause some workflows designed for nx-go not to work with GoNx.

Overview of Changes

GoNx is a modernized fork of nx-go with significant architectural changes:

Major Breaking Changes

1. Modern Nx-only: Requires Nx 21.x or later
2. No project.json generation: Uses inferred tasks instead
3. Changed command execution: Runs from project root instead of workspace root
4. Removed go.work creation: Now opt-in via configuration
5. Removed legacy generators: convert-to-one-module is no longer available

New Features

1. Inferred tasks: Automatic task detection and configuration
2. Cacheable operations: All tasks are properly cached
3. CreateNodesV2: Latest Nx project detection API
4. Version Actions: Proper Go versioning with Nx Release
5. Publish executor: Automated registry publishing

Migration Steps

Step 1: Prerequisites

Before starting the migration:

1. Upgrade Nx: Ensure you’re on Nx 21.x or later
2. Update Go: Use a stable Go version (1.21+ recommended)
3. Backup your workspace: Create a backup before making changes
4. Review project structure: Understand your current setup

Step 2: Remove nx-go Plugin

Remove the original nx-go plugin:

npm uninstall @nx-go/nx-go
# or
pnpm remove @nx-go/nx-go
# or
yarn remove @nx-go/nx-go

Step 3: Install GoNx

Install the GoNx plugin:

npm install @naxodev/gonx
# or
pnpm add @naxodev/gonx
# or
yarn add @naxodev/gonx

Step 4: Update Nx Configuration

Update your nx.json to use GoNx:

{
  "plugins": [
    {
      "plugin": "@naxodev/gonx",
      "options": {
        "addGoDotWork": false
      }
    }
  ]
}

Remove any nx-go specific configuration.

Step 5: Handle project.json Files

GoNx uses inferred tasks, so you can remove project.json files from your Go projects:

Caution

Keep project.json files for non-Go projects or if you need custom task configuration.

# Remove project.json files from Go projects
rm apps/my-go-app/project.json
rm libs/my-go-lib/project.json

Tip

The inferred target configurations are available in the executor’s documentation in case modifications are needed.

Step 6: Update Scripts and CI

Update any scripts or CI configurations that reference nx-go:

Package.json Scripts

{
  "scripts": {
    "build:go": "nx run-many --target=build --projects=tag:go",
    "test:go": "nx run-many --target=test --projects=tag:go"
  }
}

CI Configuration

Update your CI to use the new executors and ensure Go is available in the environment.

Common Migration Issues

---

Issue: Projects Named Changed

Problem: GoNx changed how project names are inferred

Solution: While nx-go uses the given name for the projects or the final segment of the path as the name, GoNx uses the entire path as the project name.

Although this can make commands longer, it has two main benefits:

• Removes the disambiguation name problem.
• Aligns perfectly with the Go standard for multi-module repository tag creation.

Reference

Issue: Tasks Not Found

Problem: Nx doesn’t recognize Go project tasks.

Solution:

1. Ensure go.mod files exist in your Go projects
2. Clear Nx cache: nx reset
3. Verify plugin configuration in nx.json

Issue: Project Graph Issues

Problem: Project dependencies aren’t detected correctly.

Solution:

1. Ensure Go imports are correctly structured
2. Use proper module paths
3. Clear cache and regenerate: nx reset && nx graph

Post-Migration Testing

After migration, verify everything works:

1. Project Detection

nx show projects

2. Task Execution

nx build my-go-app
nx test my-go-lib
nx lint my-go-app

3. Project Graph

nx graph

4. Caching

nx build my-go-app
nx build my-go-app  # Should use cache

Getting Help

If you encounter issues during migration:

1. Check documentation: Review GoNx documentation thoroughly
2. Search issues: Look for similar issues on GitHub
3. Join Discord: Get real-time help on our Discord server
4. Create issue: Report bugs or request help on GitHub