Skip to content
Search...

Nx

Nx is an extensible build system with support for monorepos, integrations, and Remote Caching on Vercel.

Read the Intro to Nx docs to learn about the benefits of using Nx to manage your monorepos.

Add Nx to an existing monorepo

To add Nx to an existing monorepo, use the following command, as described in their Getting Started guide.

terminal
npx add-nx-to-monorepo

Create a new monorepo with Nx

To create a new Next.js monorepo with Nx, use:

terminal
npx create-nx-workspace@latest --preset=next.

You can also browse their other supported plugins and guides.

Deploy to Vercel

Ensure your Nx project is configured correctly

To ensure the best experience using Nx with Vercel, the following versions and settings are recommended.
  • nx version: 14.6.2 or later
  • nx-cloud version: 14.6.0 or later

When using remote caching with Nx:

  • Ensure the NX_CACHE_DIRECTORY=/tmp/nx-cache is set

or

  • Set the cacheDirectory option to /tmp/nx-cache at tasksRunnerOptions.{runner}.options in your nx.json.

For example:

nx.json
"tasksRunnerOptions": {
  "default": {
    "runner": "nx/tasks-runners/default",
    "options": {
      "cacheDirectory": "/tmp/nx-cache"
    }
  }
}
Note: All Nx starters and examples are preconfigured with these settings.

Import your project

Create a new Project on the Vercel dashboard and import your monorepo project.

Set the Build Command

From the Build and Output Settings panel:

  1. Set the Framework to Next.js (or the framework your application is using)
  2. Set the Build Command, where <app> is the directory name of the target application within apps/, and save your changes.
terminal
npx nx build <app> --prod

Setting the Nx build command.

Set the Output Directory

From the Settings panel, set the Output Directory to point to the generated output of <app>. This can vary depending on your apps project.json outputs setting, but by default will be dist/:

terminal
dist/apps/<app>/.next

Setting the Nx output directory.

Set the Root Directory

For Nx projects, leave the root directory unchanged (set to the root of your monorepo where your nx.json can be found).

The root of the monorepo.

Setup Remote Caching on Vercel

To configure Remote Caching for your Nx project on Vercel, use the @vercel/remote-nx plugin.

Install the `@vercel/remote-nx` plugin

terminal
npm install --save-dev @vercel/remote-nx

Configure the `@vercel/remote-nx` runner

In your nx.json file you will find a tasksRunnerOptions field. Update this field so that it's using the installed @vercel/remote-nx:

nx.json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "@vercel/remote-nx",
      "options": {
        "cacheableOperations": ["build", "test", "lint", "e2e"],
        "token": "<token>",
        "teamId": "<teamId>"
      }
    }
  }
}

You can specify your token and teamId in your nx.json or set them as environment variables.

Parameter
Description
Environment Variable / .env
nx.json
Vercel Access Token
Vercel access token with access to the provided team
NX_VERCEL_REMOTE_CACHE_TOKEN
token
Vercel Team ID (optional)
The Vercel Team ID that should share the Remote Cache
NX_VERCEL_REMOTE_CACHE_TEAM
teamId
Note: When deploying on Vercel, these variables will be automatically set for you.

Run it!

Clear your local cache and rebuild your project.

terminal
npx nx reset
npx nx build