@actionforge/nx

Query an Nx workspace from plain Node: list every project, list the projects affected between two git SHAs, resolve projects to their source roots, and pull the whole project graph.

Why this exists

"Which projects changed between these two commits?" is the question every monorepo CI pipeline needs answered, and Nx already knows. But the original of this code was welded to @actions/exec and @actions/core, so it only ran inside a GitHub Actions runner — you could not use it from a pre-commit hook, a local script, or any other CI system.

This version shells out with node:child_process and logs through an injectable logger, so it works anywhere Node and Nx do.

This package is deliberately Nx-specific. It is not an abstraction over "any monorepo tool" — Nx's affected-graph is a real feature with real semantics, and pretending it is interchangeable with Turborepo's would make both worse.

Install

npm install @actionforge/nx

Nx itself is not a dependency — this package shells out to whatever nx your workspace already has.

Usage

import { buildNxAffectedProjects, getNxAffectedProjects } from '@actionforge/nx'

// Just the names
await getNxAffectedProjects({ baseSha: 'origin/main', headSha: 'HEAD' })
// ['api', 'web']

// Names resolved through to their source directories
await buildNxAffectedProjects({
  baseSha: 'origin/main',
  headSha: 'HEAD',
  excludes: ['e2e'],
})
// ['apps/api/src', 'apps/web/src']

API

| Function | Returns | | --- | --- | | getNxProjects({ excludes? }) | Every project name | | getNxAffectedProjects({ baseSha?, headSha?, excludes? }) | Affected project names | | getNxProject(name) | One project's full Nx configuration | | getNxSourceRoots(names) | sourceRoot for each name | | buildNxProjects({ excludes? }) | Source roots of every project | | buildNxAffectedProjects({ baseSha?, headSha?, excludes? }) | Source roots of affected projects | | buildNxGraph() | The parsed Nx project graph |

Every function accepts NxOptions:

| Option | Default | Purpose | | --- | --- | --- | | cwd | process.cwd() | Workspace root | | env | — | Extra environment variables | | timeout | — | Milliseconds before the child is killed | | logger | silent | debug/info/warn/error sink | | nxCommand | ['npx', 'nx'] | How to invoke Nx | | run | execFile | Command-runner seam |

Point nxCommand at your package manager to skip npx resolution:

await getNxProjects({ nxCommand: ['pnpm', 'exec', 'nx'] })

Errors are errors

A failed Nx command throws an NxCommandError carrying the exit code and both streams.

This is a deliberate behaviour change from the original, which caught every failure and returned []. In an affected-projects check that reads as "nothing changed, skip every downstream job" — a silently green, completely wrong build. If you genuinely want the old behaviour, opt into it explicitly:

const affected = await getNxAffectedProjects({ baseSha, headSha }).catch(() => [])

Testing code that uses this

Swap the run option for a fake instead of standing up a real Nx workspace:

import { buildNxAffectedProjects, type CommandRunner } from '@actionforge/nx'

const run: CommandRunner = async (_cmd, args) => {
  if (args.includes('projects')) {
    return { exitCode: 0, stdout: 'api\nweb\n', stderr: '' }
  }
  return { exitCode: 0, stdout: JSON.stringify({ sourceRoot: 'apps/api/src' }), stderr: '' }
}

await buildNxAffectedProjects({ run, baseSha: 'main', headSha: 'HEAD' })

License

MIT © Andrew Cates