Monorepos

A monorepo can contain multiple applications, shared packages, tooling, and infrastructure code. Each deployable application should be represented by its own Easel project.

Project root directory

Set each project's root directory to the application directory that contains its package manifest and framework configuration.

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

The build runs with the configured project root while retaining access to repository content required by the package manager and build system.

Shared packages

Commit workspace lockfiles and ensure the package manager can resolve internal packages in a clean checkout. Avoid relying on locally linked packages or uncommitted build output.

Build commands

Use the command appropriate for the workspace tool:

pnpm --filter web build

npm run build --workspace apps/web

turbo run build --filter=web

The exact command depends on the repository. Framework auto-detection can still apply within the selected project root.

Skipping unaffected deployments

Configure path-based or command-based skip behavior so a project does not rebuild when unrelated parts of the monorepo change.

A safe skip decision must include:

• The application directory
• Shared packages imported by the application
• Root lockfiles and package-manager configuration
• Shared build configuration
• Framework and deployment adapter packages

Do not skip a deployment solely because the application directory itself did not change.

Environment variables

Environment variables belong to an Easel project, not to the repository as a whole. Configure Preview and Production values separately for each application.

Preview URLs

Each project receives its own deployment, branch, and pull-request URLs. A pull request that changes several applications can therefore produce several independent Preview deployments.

Troubleshooting

When a monorepo build succeeds locally but fails on Easel, verify:

1. The project root directory.
2. The install and build commands.
3. The package-manager version and lockfile.
4. Access to shared workspace packages.
5. Environment variables used during install or build.
6. Skip logic and changed-path detection.