Programmatic control

[givenergy-dexter]

• I'd be willing to implement this feature (contributing guide)

Description

As described in #4341 it would be great to be able to programmatically control NX. Obviously the source code for the functions much exist somewhere – it may be the case they just need exposing.

Motivation

We're looking to create a yargs CLI wrapper around our monorepo. We're currently looking at having to use Node's spawn functionality to trigger nx commands programmatically during a wrapped command.

Suggested Implementation

It would be great to expose each function when installing and attempting to import nx through a Node file, for example:

const nx = require('nx')

async function main() {
  await nx.generate('<template>', '<project-name>')
}

Alternate Implementations

Rather than having arguments for each underlying option it may be worth providing an object which can be automatically generated and mapped if needed

const nx = require('nx')

async function main() {
  await nx.generate({ template: '<template>', project: '<project-name>' })
}

[FrozenPandaz]

I've converted this to a discussion so it can be discussed more.

The example of running generators programmatically is actually better done by composing generators.

Are there other use cases which you want a programmatic API for?

[tukusejssirs]

Are there other use cases which you want a programmatic API for?

@FrozenPandaz, I would like to create a fresh Nx workspace (initial scaffolding) and migrate packages (nx migrate $version and nx migrate $package@$version; for CI purposes) programmatically.

For the latter, I have quite complex update script. The complexity is due to the fact that some packages have peer deps with specific versions (absolute or version ranges) which must be installed to make the code function. I basically check for the latest supported peer dep version and migrate to that version.

For now, I use execa to run the CLI commands, however, I think it would better to do it programmatically using a package/API.

[julianobrasil]

In a project, we have an extremely customized release/versioning process, so we can't just use nx/release. In our scripts, we're using Node.js's exec to call nx affected to get the list of affected projects (we mostly want to find out whether some of the libraries, which we call apps - although they aren't really apps - were affected since a given git tag was created). It would be way more elegant to be able to find the affected projects programmatically. But... TBH, we're not unhappy with the current approach. I'm just adding it as a use case here.