Skip to content
Get packs

Guide · Open source

How to use Nx: install, run cached tasks and set up CI

Updated · written with AI from the project's own documentation and checked against our catalogue data

Nx is an open-source tool for managing a monorepo, a single repository that holds several related projects. It speeds up builds and tests by caching results for code that hasn't changed and running only the tasks affected by a change. This guide explains what Nx does, how to add it to an existing workspace, and when it is worth the effort.

Nxnrwl/nx · ★ 29.4k · MIT

Quick start

  1. 1Check your environment. Confirm you have Node.js and an npm, pnpm, or yarn workspace in your repository.
  2. 2Open your workspace root. Move to the top-level folder of the repository where your workspace is defined.
  3. 3Run nx init. Run npx nx init to add Nx to the existing workspace.
  4. 4Run your existing scripts. Run your package.json scripts as usual so Nx can cache their outputs.
  5. 5Add plugins if you use them. Optional plugins can detect tasks for tools such as Vite, Jest, Vitest or ESLint.
  6. 6Connect your CI provider. Follow the Nx CI guide to enable remote caching and affected-only runs on providers such as GitHub Actions or GitLab.

What Nx does in a monorepo

Nx is a monorepo solution for TypeScript and polyglot codebases. It caches what didn't change, runs only what's affected, and includes an integrated CI solution.

It is designed to start simple and scale as your repository grows.

  • Caching: reuses outputs for code that hasn't changed
  • Affected-only runs: executes tasks only for projects touched by a change
  • Works with existing npm, pnpm, or yarn workspaces

Check the prerequisites before you install

Nx works with an existing workspace. The source lists Node.js and npm, pnpm, or a yarn workspace as the prerequisites.

If your repository has only one project, Nx adds little value, because its caching and affected-only features are built for multi-project setups.

  • Node.js
  • npm, pnpm, or yarn workspace

Add Nx to an existing workspace with nx init

Nx is added to an existing workspace with a single command. Run it in the root of your workspace.

Nx picks up your existing package.json scripts, caches their outputs, and runs only what's affected. The source says no changes to your setup are required.

npx nx init

Run tasks and take advantage of caching

After setup, your existing package.json scripts run through Nx. Repeated runs of unchanged code can reuse cached results instead of doing the work again.

Plugins can auto-discover tasks and configure cache inputs and outputs based on your tooling. The source names Vite, Webpack, Jest, Vitest, ESLint, Gradle, Maven, .NET and Go as examples.

  • Plugins are optional
  • Tools such as Vite, Jest, Vitest, and ESLint are supported through plugin-based configuration

Connect Nx to your CI provider

Nx can connect to CI providers such as GitHub Actions, GitLab and Azure to enable remote caching, task distribution across machines, affected-only runs and automatic e2e test splitting.

The README describes CI integration with existing providers. It does not describe a fully hosted CI service, so plan your CI setup with that in mind.

  • Remote caching
  • Task distribution across machines
  • Affected-only runs in CI
  • Automatic e2e test splitting

Know when Nx is not the right fit

Nx suits teams with several related JavaScript or TypeScript projects in one repository. It is less useful for single-project repositories.

Teams that are unwilling to learn a new workspace configuration model may find the setup cost is not worth it. Comparable projects include Turborepo, Lerna, Rush and Bazel.

  • Good fit: several related JS or TS projects in one repo
  • Good fit: speeding up existing package.json scripts
  • Poor fit: single-project repositories
  • Poor fit: teams that won't learn a new configuration model

What people use it for

  • Speeding up builds and tests across several related TypeScript packages in one repository
  • Running only the tests affected by a pull request
  • Splitting end-to-end test runs across multiple CI machines
  • Adding caching to existing package.json scripts without rewriting them

Frequently asked questions

Is Nx free to use?

Nx is released under the MIT licence, according to the project's listing. The README also mentions optional Nx Cloud features for CI, so check the docs for what each offering includes.

What do I need to install Nx?

The source lists Node.js and an npm, pnpm, or yarn workspace as prerequisites. You run npx nx init in an existing workspace to add it.

Do I need to change my setup to use Nx?

The README says no changes to your setup are required. Nx picks up your existing package.json scripts and caches their outputs.

Can I use Nx with a single project?

You can, but the README's benefits centre on multi-project setups. With one project, the caching and affected-only features add little value.

What are the alternatives to Nx?

The project lists Turborepo, Lerna, Rush and Bazel as comparable projects. Compare them against your repository size, CI setup and how much configuration you want to manage.

Does Nx work with GitHub Actions?

The README says Nx connects to CI providers such as GitHub Actions and GitLab for remote caching and task distribution. It does not provide its own hosted CI service.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Nx is a good choice for teams with several related JavaScript or TypeScript projects in one repository that want faster builds and CI runs. Single-project repositories, or teams that don't want to learn a new workspace configuration model, should consider a simpler setup or one of the comparable tools.

Install options & downloads