This article was crafted using NX 20.x, Node 22.x, Npm 10.x, and Next 14.x.

How to Deploy an NX-Crafted Next.js App on Vercel

Deploying NX-crafted Next.js apps on Vercel can be tricky due to changing APIs and setups. Here’s a simple checklist to help you deploy and set up a monorepo with an integrated NX setup (multiple apps and libraries in one repo).

Step 1: Create an Integrated NX Project

Start with a empty repository containing only a README.md file.

Use the following command to create an NX workspace:

npx create-nx-workspace@latest name-of-project

In my case, I used:

npx create-nx-workspace@latest greenonsoftware

During the setup, select integrated (not standalone), which supports multiple apps and libraries in a single repository.
After setup, the default project structure will look like this:
```
- repo
   - greenonsoftware (name-of-project)
      - apps
          - kalinka
          - kalinka-e2e
```
This additional parent folder (greenonsoftware) is unnecessary and can be removed for simplicity. If you don’t remove it, you’ll need to include it in all paths when setting up Vercel.

After flattening the structure, it should look like this:
```
- repo
   - apps
       - kalinka
       - kalinka-e2e
```
Commit and push the initial setup to the main branch of your repository.

Step 2: Configure Vercel to Handle an Integrated Monorepo

In an integrated monorepo, for Next.js apps, NX stores build artifacts by default under the following path:

apps/name-of-your-app/.next

This can cause issues because the official NX documentation assumes that the build artifacts are located at:

dist/apps/name-of-your-app/.next

In older NX versions, there was a workspace.json file. In newer versions, it’s split into multiple project.json files.

To resolve this, you have two options:

Update the project.json file for your application to change the outputPath to match what Vercel expects.
Instead of modifying your NX configuration, you can adjust Vercel's settings to work with the existing structure. This method is simpler and avoids making changes to your repository (this guide will cover this approach).

To correctly configure Vercel paths, follow these steps:

Open your project in the Vercel dashboard and navigate to the Settings tab.
Configure the build command in Vercel to use NX. Use one of the following commands:
```
nx build name-of-your-app --prod
# or
npx nx build name-of-your-app --prod
```
In the Output Directory field, set the path to the default NX build directory:
```
.next
```
Set up a base path to point to the directory under apps/name-of-your-app/.

Here’s how your final configuration should look:

Working NX, Next.js, and Vercel Setup

Additional Notes on Installation

When installing dependencies, I use the npm i --legacy-peer-deps flag due to some unresolved peer dependency conflicts in my project. Depending on your package manager and the state of your dependencies, you may not need this flag.

If you encounter installation issues, try adding the --legacy-peer-deps flag to your command:

npm i --legacy-peer-deps

⚠️ Warning: While this flag can resolve installation issues, it may also introduce compatibility problems later. Use it only if you're aware of its implications and have a plan to address potential conflicts in the future.

Summary

It should work (at least it works for me). If something goes wrong (error or other issues), try Googling it or asking AI. It could be related to various factors like: NX version, Vercel updates, Next.js version, your project setup, or temporary issues.