Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: Deploying a Monorepo

Deploy several apps from one repository: root directory settings, workspaces, ignored builds, shared packages, per-app environment variables, build caching and a changed-files detector.

A monorepo keeps several projects in one Git repository: a marketing site, a web app, an API and shared packages (UI components, utilities, configuration). Teams like it because a change to a shared package and the apps that use it can ship in one pull request. Both platforms support it, but you must tell them which folder each project builds and when to skip a build.

The platforms cannot run here. Settings are described from documentation and menu names change. The runnable code is made of JavaScript stand-ins (a dependency graph and a changed-files detector), not the platforms' own engines.

Layout

TEXT
repo/
  apps/
    web/            (Next.js app)
    docs/           (static docs site)
  packages/
    ui/             (shared components)
    config/         (shared lint and TypeScript config)
  package.json      (workspaces: ["apps/*", "packages/*"])
  pnpm-workspace.yaml

Package managers such as pnpm, npm and Yarn "workspaces" link local packages together, so apps/web can import @acme/ui straight from the folder. Tools like Turborepo and Nx add task orchestration and caching on top.

One repository, several projects

You create one platform project per deployable app, each connected to the same repository:

  • Vercel: set the project's Root Directory to apps/web. Enable "Include source files outside of the Root Directory in the Build Step" so the build can see packages/ui. Vercel detects workspaces and Turborepo automatically and can use remote caching.
  • Netlify: set the Base directory to apps/web (or the monorepo's package directory), a build command such as pnpm --filter web build, and a publish directory relative to the base, such as apps/web/dist. Netlify detects many workspace setups automatically.

Each project has its own domains, environment variables and deployment list, so web can go to production while docs stays untouched.

Monorepo deploys

One repo Apps and shared packages.
One project each A platform project per app.
Root directory Tell the platform where to build.
Skip unchanged Do not rebuild every app.

Shared packages affect every app that imports them.

1 / 2

Skipping builds that do not matter

Without help, a typo fix in docs rebuilds web too, wasting minutes (Limits, Quotas and Costs). Both platforms offer a gate that runs before the build and decides whether to continue:

  • Vercel "Ignored Build Step": a command whose exit code 0 means skip the build and 1 means build. A common one is git diff --quiet HEAD^ HEAD -- apps/web packages/ui, or npx turbo-ignore for Turborepo.
  • Netlify "Ignore builds" (ignore in netlify.toml): a command where exit code 0 cancels the build, for example git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF -- apps/web packages.

Note that the exit-code conventions can feel inverted: exit 0 means "nothing changed, skip". Always verify with a test commit.

A dependency graph decides what to rebuild

Rebuild an app when it changed or when any package it depends on changed. That is a graph question. The stand-in computes, from a list of changed files, which apps must build.

JS Affected apps stand-in

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

No output.

Environment variables and secrets

Variables belong to the platform project, not the repository. So web and docs each have their own sets. Shared values (an analytics ID) can be shared at team level on Vercel or defined per site on Netlify. Keep a .env.example in each app so teammates know the names. Public variables (those exposed to browser code, like NEXT_PUBLIC_*) are baked in at build time: change one and you must rebuild.

Build speed and caching

  • Install with a lockfile and a cache: the platforms cache node_modules and package manager stores between builds.
  • Use Turborepo remote cache (Vercel integrates it) or Nx Cloud so unchanged packages replay from cache instead of rebuilding.
  • Build only what you need: pnpm --filter web... build builds web and its dependencies.
  • Avoid installing every app's dependencies for each project when workspaces allow filtering.

The next stand-in shows why caching helps, using content hashes of inputs as cache keys.

JS Build cache stand-in

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

No output.

Rollout checklist

  1. Create one platform project per app with the right root or base directory.
  2. Make sure shared packages are available to the build (source files outside root enabled).
  3. Add ignore commands and test them with commits that touch only one app.
  4. Set separate environment variables and domains per project.
  5. Confirm preview deployments appear for each affected app on a pull request.
  6. Turn on a build cache and compare build times before and after.

Common pitfalls

  • "Module not found" for @acme/ui: the build cannot see files outside the root directory, or the package is not built before the app.
  • Everything rebuilds every time: lockfile or root config counted as a change for all apps; narrow the diff paths or use a graph-aware tool.
  • Wrong Node or package manager version: pin them in package.json (engines, packageManager) or project settings.
  • A skip command that always says skip: exit-code mix-ups. Test it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you deploy two apps from one repository?

    Each deployable app is a separate platform project pointing at its folder, with its own settings and deployments.
  2. 2. A change in packages/ui should rebuild which apps?

    Shared package changes ripple to dependents, which is what dependency-graph tools compute.
  3. 3. What does exit code 0 mean for Vercel's ignored build step and Netlify's ignore command?

    Both treat 0 as 'ignore this build' which feels inverted, so test with a real commit.
  4. 4. Why does changing a public environment variable need a rebuild?

    Public values are inlined during the build, so the old value stays until you rebuild.

Summary

  • One platform project per deployable app, pointed at its folder.
  • Make shared packages visible to builds and use workspace-aware commands.
  • Skip builds when relevant files did not change, using a dependency graph or turbo-ignore.
  • Variables belong to platform projects; public ones need a rebuild.
  • Remote and local caching cut build time and minutes.

Next: Practice: Debugging Failed Deploys