Deploying a multi-application monorepo to the moon

Introduction

In this post, we will explore how to use tools like Vercel, PNPM, and Nx to build and deploy a multi-application monorepo. We'll cover the basics of each tool, the challenges of deploying single vs. multiple applications, and how to set up an effective deployment pipeline that works well with monorepos.

👉 Vercel

Vercel is a cloud platform that helps developers deploy and scale modern web projects. It supports front-end frameworks like Next.js, React, Vue, and others. By providing CI/CD pipelines and serverless functions, Vercel makes it simple to deploy applications.

Documentation

👉 PNPM

PNPM (Performant NPM) is a fast, space-efficient package manager. When managing dependencies, PNPM stores them in a way that avoids duplications and reduces the overall storage space required. This is a very useful feature for monorepos with multiple projects, as it reduces the installation times significantly.

Documentation

👉 Nx

Nx is a popular build system that supports monorepos out-of-the-box. It provides powerful tools to manage, build, and test large codebases with multiple applications and libraries. Nx helps build development workflows, enforces best practices, and optimizes builds by having a clear overview of the project's dependencies.

Documentation

Deploying an application

A visualization of a simple deployment process in a single application

If you are working on a simple application, deploying it is pretty straightforward. The CI/CD pipeline focuses on one codebase, one set of dependencies, and one deployment target.

A visualization of a complex deployment process in a monorepo

A monorepo is composed of multiple applications and libraries within a single repository. Each application can be developed and deployed independently.

Many developers prefer monorepos because they have several advantages, including shared dependencies, consistent tooling, and easier code sharing. On the other hand, working on a large monorepo introduces challenges:

• Dependency management — ensuring all projects use compatible versions of shared dependencies.

• Build coordination — building and testing only the affected parts of the repository.

• Deployment complexity — managing deployment configurations and environments for multiple applications.

Luckily, combining Vercel, PNPM, and Nx might help with solving all three!

How to deploy in Vercel?

A visualization of a simple deployment trigger in Vercel

Vercel can be set up to trigger deployments on specific events, such as merges to the master branch. To do that, you might need to configure a couple of things first:

👉 Enable automatic deployments

In the Vercel dashboard, you can enable automatic deployments for branches. Vercel will automatically deploy changes pushed to the configured branches.

👉 Configure conditional task execution

You can use the Nx's affected commands to optimize deployments. Nx can determine which projects are affected by changes and Vercel can be configured to deploy only those.

{
  "build": {
    "script": "nx affected:build"
  },
  "deploy": {
    "script": "vercel --prod"
  }
}

👉 Integrate with Github Actions

To make sure that conditional deployments are properly configured, you can add a GitHub Actions workflow to integrate Nx and Vercel:

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Install dependencies
        run: pnpm install

      - name: Build affected projects
        run: npx nx affected:build --base=origin/main --head=HEAD

      - name: Deploy to Vercel
        run: vercel --prod
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

👉 Configure routing

A visualization of deploying multiple applications within a monorepo to multiple sub-domains

Vercel supports deploying multiple applications from a monorepo using its built-in configuration. Each application can be assigned a unique sub-domain. You can specify the domains by adding the configuration to the vercel.json file at the root of your monorepo:

{
  "projects": {
    "app1": {
      "src": "apps/app1",
      "alias": "app1.yourdomain.com"
    },
    "app2": {
      "src": "apps/app2",
      "alias": "app2.yourdomain.com"
    },
    "app3": {
      "src": "apps/app3",
      "alias": "app3.yourdomain.com"
    }
  }
}

In the Vercel dashboard, you can configure custom domains and link them to the respective sub-domains defined in vercel.json.

A screenshot from the Vercel application that shows the domain configuration page

Conclusion

Deploying applications might be complicated, especially when working with large monorepos. Luckily, by combining tools like Vercel with Nx and PNPM, you can prepare a setup for deploying monorepos containing multiple applications to individual targets, all while handling conditional task execution and deployment triggers.