Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Deployments and Git Integration

Monorepos and Ignored Builds

Deploy several apps from one repository: set the root directory, use ignore commands to skip unrelated builds, and share packages with workspaces on Vercel and Netlify.

A monorepo keeps several projects in one Git repository, for example a marketing site, a web app and a shared UI package. It is convenient for sharing code, but a naive setup rebuilds everything on every push. This lesson shows how to point each platform project at the right folder and how to skip builds that do not matter.

Layout example

TEXT
my-repo/
  apps/
    marketing/    (Astro site)
    dashboard/    (Vite app)
  packages/
    ui/           (shared components)
  package.json    (workspaces)

You create one platform project per app, all connected to the same repository, each with a different root directory.

Setting the root directory

  • Vercel: during import, set Root Directory to apps/marketing (and repeat the import for apps/dashboard). There is also a toggle to include source files outside the root directory, needed when your app imports from packages/ui. Vercel detects workspaces and installs from the repository root accordingly.
  • Netlify: set the Base directory to apps/marketing. The package directory setting is used when your build tool, such as a workspace package, lives in a different place. Netlify detects many monorepo layouts (npm, yarn and pnpm workspaces) and suggests settings during setup.

Then the build and output settings are relative to that folder. For Netlify's netlify.toml, placing the file inside the app folder (or setting base) keeps each site self-contained:

TOML
# apps/marketing/netlify.toml
[build]
  base = "apps/marketing"
  command = "npm run build"
  publish = "dist"

Check your platform's documentation for whether publish is resolved relative to base, since this detail matters and is easy to get wrong. When in doubt, deploy once and read the build log's resolved paths.

Workspaces and shared packages

With npm workspaces, the root package.json lists the folders:

JSON
{
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

An app depends on a sibling with a workspace reference ("@acme/ui": "*" for npm, "workspace:*" for pnpm and yarn). The platform installs at the repository root so those links resolve. If you see an error that a workspace package cannot be found, the install is probably running inside the app folder instead of the root.

Skipping builds that are not needed

Without a rule, pushing a change to the marketing site also rebuilds the dashboard. Use an ignore command: a command that decides whether to proceed.

Vercel uses the Ignored Build Step (setting ignoreCommand in vercel.json). The command's exit code decides: exit code 0 means skip, a non-zero code means build. That is the opposite of how many people expect it.

JSON
{
  "ignoreCommand": "git diff --quiet HEAD^ HEAD -- ."
}

git diff --quiet exits 0 when there are no differences in the listed path, so the build is skipped when nothing in this folder changed. Vercel also supports skipping automatically by detecting affected projects in some monorepo tools; check the docs.

Netlify uses the ignore command in [build]. Here too, exit code 0 means skip the build and any other code means build:

TOML
[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF -- apps/marketing packages/ui"

$CACHED_COMMIT_REF is the commit of the last successful build and $COMMIT_REF is the current one, so the command compares what changed since the last good build, including the shared package.

The exit-code meaning is the same on both: 0 = skip, non-zero = build. If your ignore command errors for another reason (a typo, a missing Git history), the non-zero code makes the platform build, which is the safe default. A shallow clone with too little history can make HEAD^ unavailable, so test the command on a real build.

A change detector you can run

This stand-in does what the ignore command does: given the list of changed files and the folders a project depends on, it returns the exit code.

Node.js Ignore command logic (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Root-level config and shared lockfiles

A single lockfile at the root is normal. Changing the root package-lock.json or a root config file affects every app, so include them in each project's watch list:

Node.js Watch lists with root files (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Tools built for monorepos

Build orchestrators such as Turborepo and Nx understand the dependency graph between packages and can compute which apps are affected. Both platforms integrate with them, including shared remote build caches. You can start without them, using simple path-based ignore commands, and adopt one when the repository grows.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many platform projects do you usually create for a monorepo with two apps?

    Each app gets its own project pointing at the same repository with a different root directory.
  2. 2. What does an ignore command exit code of 0 mean?

    Exit code 0 means nothing relevant changed, so the build is skipped. Any other code builds.
  3. 3. Why should a project's watch list include a shared package folder?

    If the app imports from packages/ui, changes there affect the app.
  4. 4. Why can a workspace dependency fail to resolve in a build?

    Workspace links resolve when dependencies are installed from the root.

Summary

  • Create one platform project per app and set the root (Vercel) or base (Netlify) directory.
  • Install from the repository root so workspace packages resolve.
  • Use ignore commands where exit 0 means skip and non-zero means build.
  • Watch the app's folder, shared packages and root lockfile or config files.
  • Turborepo and Nx can compute affected projects when the repository grows.

Next: Build Settings