---
slug: moon-v2.1
title: moon v2.1 - Execution plans, target deps scopes, toolchain/task settings, and more
authors: [milesj]
tags: [exec, plan, task, affected, dependencies, toolchain]
image: ./img/moon/v2.1.png
---

It's been about a month since our major v2.0 release, and we're back with a smaller, but still
impactful, v2.1 release! This release includes a new execution plan feature for `moon exec`, the
ability to target project dependencies by scope, new common toolchain settings for aliases and
dependency installation, new task options for [`affectedFiles`](/docs/config/project#affectedfiles),
and more.

<!--truncate-->

## Execution plans

The [`moon exec`](/docs/commands/exec) command is powerful, but complex invocations can mean long
CLI commands that are hard to read and easy to get wrong. In v2.1, you can now define an **execution
plan** — a JSON file that declaratively configures targets, affected filtering, graph traversal, and
pipeline behavior — and pass it with a single flag:

```json title="plan.json"
{
  "pipeline": {
    "jobTotal": 3
  },
  "targets": {
    "jobs": [["app:build", "app:test"], ["lib:build", "lib:test"], ["docs:build"]]
  }
}
```

```shell
# Runs docs:build only!
$ moon exec --plan plan.json --job 2
```

This is especially useful for CI pipelines where you need partitioned jobs, affected-only runs, or
specific failure handling. Instead of stitching together a dozen flags, drop a `plan.json` into your
repo and version-control your execution strategy.

Check out the [execution plan guide](/docs/guides/exec-plan) for the full structure and examples.

## Target project dependencies by scope

moon has always allowed you to reference dependencies of a project (external projects) within a task
using `^` syntax, for both [`inputs`](/docs/config/project#inputs) and
[`deps`](/docs/config/project#deps). However, it was quite restrictive in that it referenced _all_
project dependencies, regardless of scope (production, development, etc).

We felt it was time to change this, and in v2.1 we're introducing a new syntax that allows you to
target dependencies by scope. By default, the `^` syntax will still reference all dependencies, but
you can now specify a scope by suffixing the `^` with one of the following:

- `development` / `dev`
- `production` / `prod`
- `build`
- `peer`

```yaml
tasks:
  build:
    command: 'tsc'
    deps:
      # Depend on build tasks in production level project dependencies
      - '^production:build'
    inputs:
      # Source files of all production level project dependencies
      - 'project:^production'
```

## New common toolchain settings

Going forward, we want to provide more customization for toolchains, enabling you to curate the
experience you want. The first step in this process is introducing 2 new settings that are common
across all toolchains.

### `inheritAliases`

Aliases are a feature of projects that allow for alternate names to be used when referencing them.
Aliases cannot be configured manually and instead are inferred from toolchains, typically by
extracting the `name` field from a manifest file (`package.json`, `Cargo.toml`, `pyproject.toml`,
etc).

This happens automatically, but what if you don't want to use aliases? Or there are conflicting
aliases across projects? In v2.1, we're introducing a new common toolchain setting called
[`inheritAliases`](/docs/config/toolchain#inheritaliases) that allows you to disable this feature.
When set to `false`, no aliases will be inferred for any projects using that toolchain.

```yaml title=".moon/toolchains.yml"
javascript:
  inheritAliases: false
```

> We've also updated duplicate aliases to no longer be a hard error, and instead will apply to the
> first encountered project.

### `installDependencies`

When you run a task, all toolchains associated with the task will automatically install dependencies
if they've determined that they need to (lockfile changes, dependency updates, etc). This is a great
feature for ensuring that your environment is always up to date, especially when switching branches,
but it can be a bit too much for some use cases.

In v2.1, we're introducing another common toolchain setting called
[`installDependencies`](/docs/config/toolchain#installdependencies) that allows you to disable this
feature. When set to `false`, toolchains will not automatically install dependencies before running
a task.

```yaml title=".moon/toolchains.yml"
python:
  installDependencies: false
```

> Not all toolchains support this tier 2 feature.

## New task `affectedFiles` settings

In [v2](./moon-v2.0) we introduced an object form for the the task option
[`affectedFiles`](/docs/config/project#affectedfiles), allowing you to further customize this
feature. Based on feedback from the community, we're introducing 3 new settings to this object:

- `filter` - A list of glob patterns to filter the affected files list before passing to the task.
- `ignoreProjectBoundary` - When matching affected files, ignore the project boundary and include
  workspace relative files. Otherwise, only files within the project are matched.
- `passDotWhenNoResults` - When there are no affected files after matching and filtering, use `.`
  instead of an empty value.

```yaml
tasks:
  lint:
    command: 'eslint'
    inputs:
      - 'src/**/*.{ts,tsx}'
      - '**/*.json'
      - 'eslint.config.*'
    options:
      affectedFiles:
        filter: ['**/*.tsx?']
        ignoreProjectBoundary: true
        passDotWhenNoResults: false
```

## Other changes

View the [official release](https://github.com/moonrepo/moon/releases/tag/v2.1.0) for a full list of
changes.

- Improved our local and remote detection logic. We now also check for common remote devboxes
  (GitHub Codespaces, Gitpod, etc) in addition to CI environments.
- Added a new task option, [`runInSyncPhase`](/docs/config/project#runinsyncphase), that will run
  the task during `moon sync` commands.
- **Go**
  - Will now run `go list --deps` to determine project relationships while extending the project
    graph.
- **Python**
  - Normalized package/dependency names to PEP 503 during graph extending.
  - Fixed an issue where package manager toolchain settings were not being inherited correctly.
- **TypeScript**
  - Added a `pruneProjectReferences` setting that prunes non-moon managed project references when
    syncing.
