Melos Documentation

Melos is a CLI tool designed to manage Dart projects containing multiple packages, commonly referred to as mono-repos. It facilitates managing large codebases by allowing multiple independent packages to coexist within a single repository.

Key capabilities include:

• Versioning & Changelogs: Automatic versioning and changelog generation.
• Publishing: Automated publishing of packages to pub.dev.
• Dependency Management: Local package linking and installation.
• Command Execution: Running commands simultaneously across multiple packages.
• Introspection: Listing local packages and their dependencies.
• CI/CD Integration: Works effectively in CI/CD environments (e.g., via the Melos GitHub Action).

A Melos workspace is organized around a root pubspec.yaml that defines the workspace members. A typical structure looks like this:

my-melos-repo/
  pubspec.yaml
  packages/
    package-1/
      pubspec.yaml
    package-2/
      pubspec.yaml

The specific locations of these packages must be explicitly listed in the workspace section of the root pubspec.yaml.

When a package is versioned, Melos can automatically update the pubspec.yaml files of its dependents.

• Update constraints: By default, Melos updates version constraints in dependents. Disable this with --no-dependent-constraints.
• Bump dependents: If a dependent is not being versioned itself, Melos will create a patch version bump for it. Disable this with --no-dependent-versions.

Note: Dependents are not subject to the package filters applied to the primary versioning command.

If you define a custom script with the same name as a built-in Melos command, your custom script takes precedence. This allows you to customize the behavior of standard commands like format to match your workspace requirements.

Example: Overriding the format command:

scripts:
  format: dart run custom_formatter

Both melos format and melos run format will now execute your custom script.

If you use private Git-hosted packages instead of pub.dev, Melos can update the ref in your pubspec.yaml files to point to the new package version tags.

To enable this, add command/version/updateGitTagRefs: true to your root pubspec.yaml.

Example workflow: If a dependency is defined as:

dependencies:
  internal_dep:
    git:
      url: git@github.com:org/repo.git
      path: packages/internal_dep
      ref: internal_dep-v0.0.1

When internal_dep is patched via melos version, Melos will update the ref to internal_dep-v0.0.2 in all consuming packages.

After updating pubspec.yaml files and changelogs, Melos commits the changes and adds a git tag for each package in the format <package-name>-v<version>.

Customizing the commit process

• Disable tagging: Use --no-git-tag-version to prevent Melos from creating git tags.
• Pre-commit hook: You can run custom code before the version commit is created by defining a script in your root pubspec.yaml under command/version/hooks/preCommit.
  • Note: You must manually stage any changes made within this hook if you want them included in the version commit.

By setting useRootAsPackage: true, the root directory containing your workspace configuration is treated as a package. This allows the root to be included in workspace operations like scripts, filtering, and categorization.

Use cases:

• Migrating legacy projects where the main app is in the root.
• Projects where the primary Flutter app lives at the repository root.
• Single package projects (non-monorepos) that want to use Melos features like melos version, melos publish, and melos run.

melos:
  useRootAsPackage: true
  categories:
    app:
      - "."
    packages:
      - "packages/**"

Lifecycle hooks are no longer defined in scripts. They are now defined under command/<name>/hooks.

Common mappings include:

• bootstrap -> command/bootstrap/hooks/pre and command/bootstrap/hooks/post
• clean -> command/clean/hooks/pre and command/clean/hooks/post
• version -> command/version/hooks/preCommit (replaces the old version hook) and command/version/hooks/post

Scripts are executed in a shell: cmd.exe on Windows and sh on other platforms.

To ensure cross-platform compatibility, use $VARIABLE or ${VARIABLE} for referencing environment variables defined in the env block or injected MELOS_* variables. Avoid using %VARIABLE% (Windows-only).

Shell behavior notes:

• macOS/Linux (sh): Uses standard shell quoting. Single quotes (') prevent expansion; double quotes (") allow it.
• Windows (cmd.exe): Melos substitutes the value directly before handing it to the shell, meaning expansion happens regardless of quoting, but standard cmd.exe special character rules apply.

Running melos init generates the following structure:

• melos.yaml: The workspace configuration file. It contains the workspace name, package locations (defaults to ['packages/*'] and optionally apps/*), and any additional glob patterns provided via --packages.
• pubspec.yaml: The root package configuration. It includes the project name (matching the workspace name), Dart SDK constraints, and adds melos as a dev_dependency.
• packages/: A directory that is always created to hold workspace packages.
• apps/: A directory created only if confirmed during the interactive setup process.