Nx CLI

Why use the Nx CLI?

The Nx CLI isn't like most command lines that accomplishes a predefined task. Nx can be configured to work with different tools and even different languages.

Nrwl and the community have created plugins that provide a base level of functionality. In addition, your organization can further customize what Nx does to fit your needs.

Nx allows you to break up your codebase into different projects. The Nx CLI provides commands to operate and manage the different parts of the codebase. These commands fall into three categories:

  • Acting on code (Build, Test, Serve)
  • Modifying code
  • Understanding the codebase

Run the nx help command to see a full list of commands in the Nx CLI.

Acting on Code

Each project can be configured with targets that can be executed on the source code of the project.

The nx run command executes a target on a single project. For convenience, you can also run nx [target] [project] which is an alias to nx run [project]:[target].

nx run my-app:build
nx build my-app

Nx also automatically caches the output of running targets so re-running the same target on the same project source code will be instant.

However, nx build is only an abstraction over what it means to "build" projects rather than tied to a certain implementation. Each target's has an executor which actually defines how to execute target on a project. You can change the executor or write an entirely custom one to fit your needs.

Along with running a target on a single project, Nx provides some commands to run the same target across multiple projects.

The nx run-many command runs the same target name across a list of projects.

nx run-many --target build --projects app1,app2
nx run-many --target test --all # Runs all projects that have a test target, use this sparingly.

The nx affected command isolates set projects that may have changed in behavior and runs a target across them. This is more efficient than running all projects every time.

nx affected --target build

Modifying Code

The nx generate command generates and modifies code.

nx generate app my-app
nx generate @nrwl/angular:lib shared-button
nx generate @nrwl/angular:storybook-configuration shared-button # Configures storybook for a UI library

Again, like nx run, nx generate is only an abstraction over generating code. nx generate can generate anything you want via generators. Generators can be installed as part of a plugin or developed locally within an Nx workspace to fit the needs of your organization.

A Workspace Generator is custom generator for your workspace. nx generate workspace-generator my-generator generates a workspace generator which can be run with the nx workspace-generator command. This can be useful to allow your organization to consistently generate projects according to your own standards.

nx workspace-generator my-generator

Upgrading a package is not always as simple as bumping the version in package.json. The nx migrate command facilitates not only managing package versions but also runs migrations specified by package mantainers. See the full guide to updating Nx.

nx migrate latest # Updates the version of Nx in `package.json` and schedules migrations to be run
nx migrate --run-migrations # Runs the migrations scheduled by the previous command.

Understanding the codebase

Nx creates and maintains a dependency graph between projects based on import statements in your code and uses that information to run executors only on the affected projects in a codebase. A visual version of the dependency graph is also available to help developers understand the architecture of the codebase.

The nx dep-graph command displays this dependency graph in a web browser for you to explore.

nx dep-graph
nx dep-graph --watch # Updates the browser as code is changed
nx affected:dep-graph # Highlights projects which may have changed in behavior

The nx list command lists the currently installed Nx plugins and other available plugins. The nx list command can list the generators and executors that are available for a plugin.

List installed plugins:

nx list
nx list @nrwl/angular # Lists capabilities in the @nrwl/angular plugin

Common Environment Variables

There are some environment variables that you can set to log additional information from Nx.

  • Setting NX_VERBOSE_LOGGING=true will print debug information useful for troubleshooting.
  • Setting NX_PERF_LOGGING=true will print debug information useful for profiling executors and Nx itself.

Nx and Angular CLI

Nx supports Angular Devkit. When you run nx build myapp, and the build target for myapp is implemented using Angular Devkit, Nx behaves exactly the same as the Angular CLI. When you run nx g component mycmp, once again, Nx invokes the same schematic. You can think of Nx wrapping the Angular CLI. The results of running commands produces the same result, except that running nx is often a lot faster.

How?

Nx CLI uses advanced code analysis and computation caching to reuse previous computation results, when possible, and supports more commands than the Angular CLI. For example, it can run a target against many projects in parallel, run a target against a project and its dependencies, etc.

Decorating the Angular CLI

Because Nx does everything the Angular CLI does and more, all workspaces have a decorate-angular-cli.js file. This file remaps ng to invoke nx, which then invokes the Angular CLI with Nx's improvements. In other words, calling ng invokes the Nx-wrapped version of the Angular CLI.