Deploying Monorepo to Vercel Guide: Step-by-Step for Turborepo and Nx

Managing multiple projects in a single repository is a game-changer for developer experience, but it often turns into a nightmare during the deployment phase. If you’ve ever accidentally triggered five different project builds because you changed a single README file in the root, you know exactly what I mean. This deploying monorepo to vercel guide is designed to solve that specific headache.

In my experience, the biggest mistake developers make is treating a monorepo like a standard single-app project. Vercel has excellent native support for monorepos, but you have to tell it exactly where your apps live and when they should actually build. Whether you are using Turborepo, Nx, or just a simple folder structure, the logic remains the same.

Prerequisites

• A GitHub, GitLab, or Bitbucket account with your monorepo pushed.
• A Vercel account linked to your git provider.
• A monorepo structure (e.g., /apps for applications and /packages for shared libraries).
• Basic familiarity with npm, yarn, or pnpm.

Step 1: Connect Your Repository

Start by logging into your Vercel Dashboard. Click “Add New…” and select “Project”. Import your monorepo from your git provider. At this stage, Vercel will detect the repository, but it won’t know which specific app within the monorepo you want to deploy.

Step 2: Configure the Root Directory

This is the most critical part of any deploying monorepo to vercel guide. You cannot leave the Root Directory as the project root if you have multiple apps.

1. In the “Project Settings” during the import flow, look for the Root Directory field.
2. Click “Edit” and navigate to the specific application folder (e.g., apps/web).
3. Ensure the checkbox “Include source files outside of the Root Directory in the Build Step” is checked. This allows Vercel to access your shared /packages folder for dependencies.

As shown in the image below, correctly mapping the root directory ensures that Vercel only targets the specific build artifacts for that application while still having access to the global node_modules.

Step 3: Optimizing the Build Command

If you’re using a tool like Turborepo, you don’t want Vercel to run a generic npm run build. You want to leverage the remote cache to speed things up. I recommend using the turbo command in your build settings:

# Example Build Command for Turborepo
npm run build --filter=web...

The --filter=web... flag tells Turbo to build the ‘web’ app and all of its local dependencies in the /packages folder, ignoring everything else. This significantly reduces build times and prevents the “out of memory” errors common in large monorepos.

Step 4: Managing Ignored Build Steps

One of the most frustrating parts of monorepos is the “ghost build”—where Vercel redeploys your admin panel even though you only changed the frontend. To fix this, go to Settings > Git > Ignored Build Step.

Enter a custom command to tell Vercel whether to proceed with the build. For Turborepo, you can use:

npx turbo-ignore

This command checks if any changes actually affected the current project. If not, Vercel will skip the build entirely, saving you precious build minutes. If you are weighing different hosting strategies, you might find that railway.app vs vercel offers different trade-offs for backend services in a monorepo, but for frontend, Vercel’s ignore step is unmatched.

Pro Tips for Monorepo Scaling

• Use pnpm Workspaces: I’ve found that pnpm is significantly faster and more disk-efficient than npm or yarn for monorepos. Vercel supports pnpm natively.
• Environment Variables: Don’t define global variables in the root. Define them at the project level in Vercel so the admin app doesn’t have access to the web app’s secrets.
• Shared UI Libraries: Keep your UI components in a separate package (e.g., @repo/ui). When you update a component, Vercel’s build cache will only rebuild the apps that actually import that specific component.

Troubleshooting Common Issues

Error: “Module not found” for shared packages

This usually happens because the “Include source files outside of the Root Directory” setting was unchecked. Double-check your project settings and trigger a manual redeploy.

Builds taking too long

Check your turbo.json configuration. Ensure you have defined the correct outputs (like .next or dist) so Vercel can cache them effectively. If you’re dealing with heavy Docker-based workflows, you might want to look into github actions for docker deployment for your backend services while keeping the frontend on Vercel.

What’s Next?

Now that your monorepo is deploying smoothly, you can focus on optimizing your CI/CD pipeline. If you find Vercel’s pricing becomes a hurdle for your internal tools, you might explore how to deploy nextjs on hetzner for a more cost-effective, self-hosted alternative.