Pnpm

name: pnpm-task-orchestration description: Declare cross-project task graphs (tasks/dependsOn), concurrency groups, priorities, and run cached CI pipelines

Workspace Task Orchestration

pnpm -r run <script> schedules a graph of workspace tasks. A task is <project>#<script>; it becomes ready once every task it depends on succeeds, and ready tasks run under --workspace-concurrency. Independent tasks run in unpredictable order.

Declaring task dependencies

Configure under tasks in pnpm-workspace.yaml:

tasks:
  build:
    dependsOn:
      - ^build        # build in each workspace dependency
  test:
    dependsOn:
      - build         # build in the same project

• build → the build task in the same project.

• ^build → the build task in each selected workspace dependency.

• A task with no tasks entry defaults to depending on the same task in its workspace deps (an unconfigured build behaves as dependsOn: ['^build']), preserving deps-before-dependents order.

• Once a task has an entry, an omitted dependsOn means dependsOn: []. If you set another field (e.g. concurrency) and still want topological order, declare dependsOn: ['^build'] explicitly.

• Task deps stay within the --filter/includeWorkspaceRoot selection. A project missing the named script is a pass-through (reported skipped, doesn't break the chain).

Per-task concurrency

tasks:
  build:
    concurrency: 2          # max 2 instances of build across projects
    dependsOn: ['^build']

Separate from --workspace-concurrency; a task waiting for its slot doesn't occupy a workspace slot.

Concurrency groups (v12.5.0)

Machine-wide limits shared across pnpm processes that use the same stateDir (including pnpm pipeline):

tasks:
  test:rust:
    concurrencyGroup: cargo
    dependsOn: []
concurrencyGroups:
  cargo: 2                  # at most 2 cargo tasks at once, across processes

• A nested pnpm run in the same group reuses its parent's slot. Slots release on process exit/crash.

• A missing/zero group limit doesn't restrict. Changing stateDir creates a separate slot pool.

Task priority (v12.6.0)

priority (integer, default 0) orders waiting tasks for available slots — higher runs first, ties broken by arrival:

tasks:
  build:critical: { concurrencyGroup: build, priority: 10 }
  build:cleanup:  { concurrencyGroup: build, priority: -1 }

Inspecting groups (v12.6.0)

pnpm tasks status [groups...]   # running + waiting tasks per group
pnpm pm tasks status            # force built-in if a "tasks" script shadows it

A subcommand is required. A waiting task shows its priority only when non-zero.

Inspecting the graph

pnpm -r run --dry-run build         # stable topological ordering, no scripts run
pnpm -r run --dry-run --json test   # nodes + edges as JSON

Recursive run options

• --resume-from <pkg> — resume at a package's task, skipping tasks a prior run of the same invocation recorded as passed.

• --reverse — reverse every edge (dependents run first).

• --no-bail — keep running independent ready tasks after a failure; tasks depending on the failed one are skipped (default --bail stops dispatching and kills running tasks: SIGTERM, then SIGKILL after 2s on Unix). Accepted only by run/exec/test/start/stop/rebuild/install-test.

• --workspace-concurrency defaults to min(4, available CPU cores), respecting container CPU quotas; <= 0 means cores minus abs value (min 1).

• --report-summary statuses: passed|queued|running|skipped|failure (failures carry prefix/message); non-requested tasks are keyed <dir>#<task>.

• Output is inherited when only one script can run at a time; otherwise piped. Use --stream for immediate prefixed output or --aggregate-output.

Cycles

A cycle fails before any script with ERR_PNPM_TASK_CYCLE. Set ignoreWorkspaceCycles: true only for deliberate cycles (pnpm warns and drops ordering among members).

Commands that ignore tasks

--no-sort and --parallel (implies --no-sort) ignore tasks declarations. Recursive exec has no script name so it doesn't join dependsOn, but still uses dependency-aware scheduling and --resume-from.

pnpm pipeline (v12.4.0, experimental)

Runs a named set of tasks the way a CI job would: frozen install, then the affected projects' task graph, with cached results restored.

tasks:
  build: { dependsOn: ['^build'], outputs: ['dist/**'], inputs: ['src/**'], env: ['NODE_ENV'] }
  test:  { dependsOn: ['build'], outputs: [] }
  lint:  { outputs: [] }
pipelines:
  default: [build, test, lint]
  release: [build]

pnpm pipeline           # runs the "default" pipeline
pnpm pipeline release
pnpm pipeline --dry-run --json
pnpm pipeline --full    # every project, not just affected-since-base
pnpm pipeline --base <ref>   # affected diff base (default origin/main, or pipelineBase)
pnpm pipeline --no-cache

• Caching: a task is cacheable only when it declares outputs (outputs: [] = "produces no files", makes a linter/test cacheable). inputs narrows the cache key (+glob adds to the default); env names hashed vars; cache: false opts out. The key also covers script text, dependency task keys, the lockfile, and the runtime. A hit restores files and replays logs.

• A plain recursive pnpm run never restores from the pipeline cache; outputs/inputs/env/cache/cargoTargetDir are read by pnpm pipeline only.

• Remote cache: a remoteCache setting shares signed results through a Turborepo-API server (e.g. Vercel Remote Cache) or pnpr. Machines restore only results signed by their trustedKeys; CI publishes with PNPM_REMOTE_CACHE_URL/_TEAM/_TRUSTED_KEYS/_PRIVATE_KEY/_KEY_ID/_BUILDER_ID/_PUBLISH=true. Published results include output files and terminal logs. A missing, untrusted, or unreachable cache is just a miss.

• Accepts every pnpm install option (for its frozen install). Errors: ERR_PNPM_NO_PIPELINES, ERR_PNPM_UNKNOWN_PIPELINE, ERR_PNPM_PIPELINE_FAIL. --report/--report-to <url> submit run data; --repo with --watch/--once/--interval watches a repo.

• Cargo build state: cargoTargetDir: target keeps a task's Cargo target dir between runs/worktrees via immutable snapshots.

Other dependency-aware commands

Workspace install, rebuild, pack, publish, stage, and lifecycle work start a project's work as soon as its workspace deps finish — following the package graph (not tasks), no longer waiting for unrelated topological groups.

<!-- Source references: - https://pnpm.io/workspace-task-orchestration - https://pnpm.io/cli/tasks - https://pnpm.io/cli/pipeline -->