# Melos Migration

> Use when upgrading a workspace to Melos 8.x from Melos 7.x or older, when a repository still has a melos.yaml file, `packages:` globs, per-package pubspec_overrides.yaml files, `select-package`, hooks defined as scripts, or `run` plus `exec` scripts, or when Melos reports an unsupported configuration format.

- Skill: `invertase/melos-migration` (Agent Skill)
- Install (CLI): `npx get-skill add invertase/melos-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/invertase/melos-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: invertase (https://skillmd.com/u/invertase)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/invertase/melos-migration

---


# Migrating to Melos 8.x

Melos 7 moved to [pub workspaces](https://dart.dev/tools/pub/workspaces) and
Melos 8 changed the `exec` script format. Melos 8.x requires Dart 3.9.0 or
newer. Melos reports a descriptive error, including the converted
configuration, when it finds the old `exec` format.

## Guidelines

- Do the whole migration in one change: `melos.yaml` and the old `exec`
  format cannot be mixed with the new layout.
- Run `melos clean` with the old Melos version first, to remove the generated
  `pubspec_overrides.yaml` files, then upgrade.
- Keep the content of the old `melos.yaml` except `name` and `packages`; it
  moves under `melos:` in the root `pubspec.yaml` unchanged, apart from the
  script and hook changes below.
- Add `resolution: workspace` to every package `pubspec.yaml`.
- After the migration run `melos bootstrap` and commit the root
  `pubspec.lock`.

## 6.x (or older) to 8.x

Before:

```yaml
# melos.yaml
name: my_workspace
packages:
  - packages/**
scripts:
  test:
    run: dart test
    exec:
      concurrency: 1
    select-package:
      dir-exists: test
```

After, root `pubspec.yaml`:

```yaml
name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client
dev_dependencies:
  melos: ^8.0.0

melos:
  scripts:
    test:
      exec:
        command: dart test
        concurrency: 1
      packageFilters:
        dirExists: test
```

Each package `pubspec.yaml`:

```yaml
name: helper
environment:
  sdk: ^3.9.0
resolution: workspace
```

Steps:

1. `melos clean` to remove the `pubspec_overrides.yaml` files.
2. Create or update the root `pubspec.yaml` with `workspace:`, the `melos`
   dev dependency and the `melos:` section.
3. Add `resolution: workspace` to every package.
4. Delete `melos.yaml`.
5. Convert the scripts as described below.
6. `melos bootstrap`.

`workspace:` supports globs from Dart 3.11; on older SDKs list each package.

### Root package

Melos 6 allowed `.` in `packages:`. In Melos 7+ either set
`useRootAsPackage: true` in the `melos` section, or move the root app into a
subdirectory and add it to `workspace:`.

## 7.x to 8.x

### `exec` scripts

`run` and `exec` are mutually exclusive. Move the command into `exec` under
`command`:

```yaml
# Before (rejected by Melos 8)
test:
  run: dart test --concurrency=1
  exec:
    concurrency: 1

# After
test:
  exec:
    command: dart test --concurrency=1
    concurrency: 1
```

A string `exec` is unchanged: `exec: dart test`.

### Build numbers

`melos version` now keeps and increments an integer build number
(`3.0.0+11` becomes `4.0.0+12`), and a patch release below `1.0.0` bumps the
patch component (`0.1.0` becomes `0.1.1`, not `0.1.0+1`).

### `melos analyze`

Removed in 7.0.0, restored in 8.1.0 with support for all package filters.

## Older formats still found in the wild

Melos 2 to 3:

- Hooks were scripts named after the command. They are now
  `command/<name>/hooks/pre` and `post`:
  `bootstrap` to `command/bootstrap/hooks/pre`, `postbootstrap` to
  `command/bootstrap/hooks/post`, `clean` and `postclean` likewise,
  `version` to `command/version/hooks/preCommit`, `postversion` to
  `command/version/hooks/post`.
- `select-package` was renamed to `packageFilters` and its filter names are
  camel cased (`dir-exists` to `dirExists`).
- `--since` was replaced by `--diff`.
- `command/bootstrap/usePubspecOverrides` was removed.
- `includeScopes`, `linkToCommits` (when `repository` is set) and
  `workspaceChangelog` default to `true`.

Melos 3 to 4:

- `--no-git-tag-version` no longer skips the commit; add
  `--no-git-commit-version` for that.

## Checklist

- [ ] No `melos.yaml` in the repository.
- [ ] Root `pubspec.yaml` has `workspace:`, `dev_dependencies: melos` and a
      `melos:` section.
- [ ] Every package has `resolution: workspace`.
- [ ] No `pubspec_overrides.yaml` generated by Melos in the packages
      (remove `pubspec_overrides.yaml` from `.gitignore` only if nothing else
      uses it).
- [ ] No script has both `run` and an `exec` map.
- [ ] No `select-package`, no kebab case filter names.
- [ ] Hooks live under `command/<name>/hooks`.
- [ ] `melos bootstrap` succeeds and `pubspec.lock` is committed.

## References

- Migrations guide:
  https://melos.invertase.dev/~melos-latest/migration
- Configuration overview:
  https://melos.invertase.dev/~melos-latest/configuration/overview

