Deploying Nx to Vercel

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.

1. Ensure your Nx project is configured correctly

   If you haven't already connected your monorepo to Nx, you can follow the Getting Started on the Nx docs to do so.

   To ensure the best experience using Nx with Vercel, the following versions and settings are recommended:

   • Use nx version 14.6.2 or later
   • Use nx-cloud version 14.6.0 or later

   There are also additional settings if you are using Remote Caching

   All Nx starters and examples are preconfigured with these settings.

2. Import your project

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

   Vercel handles all aspects of configuring your monorepo, including setting build commands, the Root Directory, the correct directory for npm workspaces, and the ignored build step.

3. Next Steps

   Your Nx monorepo is now configured and ready to be used with Vercel!

   You can now setup Remote Caching for Nx on Vercel or configure additional deployment options, such as environment variables.

nx-ignore provides a way for you to tell Vercel if a build should continue or not. For more details and information on how to use nx-ignore, see the documentation.

Before using remote caching with Nx, do one of the following:

• 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:

"tasksRunnerOptions": {
  "default": {
    "runner": "nx/tasks-runners/default",
    "options": {
      "cacheDirectory": "/tmp/nx-cache"
    }
  }
}

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

1. Install the @vercel/remote-nx plugin

   terminal

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

2. 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

   When deploying on Vercel, these variables will be automatically set for you.

3. Run it!

   Clear your local cache and rebuild your project.

   terminal

   npx nx reset
   npx nx build