Use Nx for EOS task execution

Date: 2026-09-10

Status

Accepted. PR #491 completed AI-347. This decision supersedes the Turborepo decision.

Context

At the migration, EOS had 16 pnpm workspaces. Six defined executable tasks. The repository used Turborepo for package checks, finalisation, and CI cache management.

The migration introduces the Nx project graph while it preserves package scripts, package names, and the existing directory structure. Tests and tools also read shared files outside their workspace. Those relationships need explicit cache inputs.

Decision

Use Nx for task execution and local cache management. Keep pnpm for package management, Changesets for releases, and APM for shared guidance.

Use mise to install and select tool versions. Disable its package task inference. Use direct Nx commands for project tasks and pnpm for dependencies, repository maintenance, and direct CLI commands. Keep root pnpm task aliases that call Nx for compatibility.

Define tasks through existing package scripts. Use shared Nx defaults and workspace exceptions. Keep the docs build uncached because it reads external sources. Mark development and preview tasks as continuous.

Define repository checks in separate Nx projects. The finalise-change skill runs the complete verification target set through nx affected. Lefthook passes filenames to Nx, which calls the check tools directly.

Keep the existing CI jobs and required check names. Run build, typecheck, lint, format, and test targets for affected projects. Preserve the existing mutation scope. Fetch full Git history and use nx-set-shas to select the base and head. Require a successful workflow as the base. This GitHub integration does not require Nx Cloud.

Use local cache only for the initial migration. Remote cache configuration is separate work. The deprecated Nx S3 cache package does not provide a suitable replacement for the former Turbo R2 sidecar.

Consequences

Local commands and CI use the same Nx task configuration. Tests cover task selection and finalisation behaviour. Shared plugin tests explicitly depend on child plugins and include their files.

Nx inputs determine which projects CI checks. Maintainers must declare shared files as inputs and use full workspace checks when the affected scope is uncertain.

CI jobs no longer share task artifacts through R2. Each job must compute an uncached task result at least once. The pnpm cache and Stryker baseline artifacts remain available.

Contributors use Nx commands with declared dependency tasks and the Nx cache. Direct pnpm workspace scripts remain available for diagnosis but bypass both.

The migration does not introduce framework plugins, Nx Release, distributed agents, package boundary rules, or a new remote cache service.

Rollback

Revert the migration commits to restore Turbo commands and configuration. Keep the former R2 bucket and repository secrets through the rollback period. Cache artifacts need no conversion because each runner can rebuild them.