Monorepos

Create one Easel project for each application you deploy from a monorepo, and connect each project to the same repository.

Set each project's root directory

In Project settings → Build, set Root directory to the folder that holds the application's package manifest and framework configuration, and pick your Monorepo tool.

repository/
  apps/
    web/          ← Easel project: web
    docs/         ← Easel project: docs
  packages/
    ui/
    config/

Builds run from the root directory but can still reach the rest of the repository, so workspace packages resolve. Commit your lockfile, and don't rely on locally linked packages or uncommitted build output.

To deploy several linked projects from your machine, see Deploy from the CLI.

Build commands

Framework detection still works inside the root directory. If you need a workspace command, set it as the build command:

pnpm --filter web build

npm run build --workspace apps/web

turbo run build --filter=web

Skip unaffected deployments

Skip unaffected deployments is on by default, and the switch appears under Root directory once you pick a monorepo tool. It needs a workspace definition: workspaces in the root package.json, or pnpm-workspace.yaml. When a push doesn't affect the project, Easel marks the deployment Skipped instead of building it.

A project is affected when a push changes any of these:

• Files under the project's root directory.
• A workspace package the project depends on, directly or through other packages. Declare each dependency in the project's package.json.
• A package the project references with file: or link:.
• A root-level install file, such as a lockfile, the root package.json, pnpm-workspace.yaml, .npmrc, turbo.json, .nvmrc, or patches/.

A project whose root directory is a workspace package also deploys when a push changes files outside every package, such as a root README.md or scripts/, since Easel can't tell what those files affect.

A root directory outside the workspace, such as examples/demo with its own package.json, works too. It deploys only for changes under its root, its file: dependencies, workspace packages it names, and root install files. Changes inside it don't deploy your workspace projects.

Easel compares the push with the last Ready deployment on the same branch. A branch's first push is compared with the last Ready production deployment, so a new branch builds only the projects it changes.

For your own rule, set an Ignored build step command such as npx turbo-ignore. See Skipping deployments.

Per-project settings

Environment variables, domains, and settings belong to each project, not to the repository. To reuse a value across projects, share it from the workspace. See Shared variables.

Each project gets its own deployments and URLs, so a pull request that changes several applications produces a Preview deployment for each one.