Melos

A tool for managing Dart projects with multiple packages.


About

Splitting up large code bases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated really fast.

To solve these (and many other) problems, some projects will organize their code bases into multi-package repositories (sometimes called monorepos)

Melos is a tool that optimizes the workflow around managing multi-package repositories with git and Pub.


What does a Melos workspace look like?

A default file structure looks something like this:

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

The location of your packages can be configured via the melos.yaml configuration file if the default is unsuitable.


What can Melos do?

  • 🔗 Link local packages in your workspace together without adding dependency overrides.
  • 📦 Automatically version, create changelogs and publish your packages using Conventional Commits.
  • 📜 Pre-define advanced custom scripts for your workspace in your melos.yaml configuration to use via melos run [scriptName]. Anyone contributing to your workspace can just run melos run to be prompted to select a script from a list with descriptions of each script.
  • ⚡ Execute commands across your packages easily with melos exec -- command here with additional concurrency and fail-fast options.
    • Environment variables containing various information about the current package and the workspace are available in each execution.
    • Can be combined with all package filters.
  • 🎯 Many advanced package filtering options allowing you to target specific packages or groups of packages in your workspace.
    • --no-private
      • Exclude private packages (publish_to: none).
    • --[no-]published
      • Filter packages where the current local package version exists on pub.dev. Or "-no-published" to filter packages that have not had their current version published yet.
    • --[no-]nullsafety
      • Filter packages where the current local version uses a "nullsafety" prerelease preid. Or "-no-nullsafety" to filter packages where their current version does not have a "nullsafety" preid.
    • --[no-]flutter
      • Filter packages where the package depends on the Flutter SDK. Or "-no-flutter" to filter packages that do not depend on the Flutter SDK.
    • --scope=<glob>
      • Include only packages with names matching the given glob.
    • --ignore=<glob>
      • Exclude packages with names matching the given glob.
    • --since=<ref>
      • Only include packages that have been changed since the specified ref, e.g. a commit sha or git tag.
    • --dir-exists=<dirRelativeToPackageRoot>
      • Include only packages where a specific directory exists inside the package.
    • --file-exists=<fileRelativeToPackageRoot>
      • Include only packages where a specific file exists in the package.
    • --depends-on=<dependantPackageName>
      • Include only packages that depend on a specific package.
    • --no-depends-on=<noDependantPackageName>
      • Include only packages that don't depend on a specific package.
  • ♨️ Advanced support for IntelliJ IDEs with automatic creation of run configurations for workspace defined scripts and more on workspace boostrap.
    • Vscode code doesn't require advanced integration to work.

Who is using Melos?

The following projects are using Melos:

Submit a PR if you'd like to add your project to the list. Update the README.md and the docs. You can also add a readme badge to your projects readme to let others know about Melos 💙.


Getting Started

Install the latest Melos version as a global package via Pub.

pub global activate melos

# Or alternatively to specify a specific version:
# pub global activate melos 0.4.1

Documentation

Documentation is available at https://docs.page/invertase/melos.


Commands

Full commands list and args can be viewed by running melos --help.

> melos --help

A CLI tool for managing Dart & Flutter projects with multiple packages.

Usage: melos <command> [arguments]

Global options:
-h, --help                                       Print this usage information.
    --verbose                                    Enable verbose logging.
    --no-private                                 Exclude private packages (`publish_to: none`). They are included by default.
    --[no-]published                             Filter packages where the current local package version exists on pub.dev. Or "-no-published" to filter packages that have not had their current version published yet.
    --[no-]flutter                               Filter packages where the package depends on the Flutter SDK. Or "-no-flutter" to filter packages that do not depend on the Flutter SDK.
    --scope=<glob>                               Include only packages with names matching the given glob. This option can be repeated.
    --ignore=<glob>                              Exclude packages with names matching the given glob. This option can be repeated.
    --since=<ref>                                Only include packages that have been changed since the specified `ref`, e.g. a commit sha or git tag.
    --dir-exists=<dirRelativeToPackageRoot>      Include only packages where a specific directory exists inside the package.
    --file-exists=<fileRelativeToPackageRoot>    Include only packages where a specific file exists in the package.
    --depends-on=<dependantPackageName>          Include only packages that depend on a specific package. This option can be repeated.
    --no-depends-on=<noDependantPackageName>     Include only packages that *don't* depend on a specific package. This option can be repeated.

Available commands:
  bootstrap   Initialize the workspace, link local packages together and install remaining package dependencies. Supports all package filtering options.
  clean       Clean this workspace and all packages. This deletes the temporary pub & ide files such as ".packages" & ".flutter-plugins". Supports all package filtering options.
  exec        Execute an arbitrary command in each package. Supports all package filtering options.
  list        List local packages in various output formats. Supports all package filtering options.
  publish     Publish any unpublished packages or package versions in your repository to pub.dev. Dry run is on by default.
  run         Run a script by name defined in the workspace melos.yaml config file.
  version     Automatically version and generate changelogs based on the Conventional Commits specification. Supports all package filtering options.

Run "melos help <command>" for more information about a command.

Lerna

This project is heavily inspired by Lerna.


README Badge

Using Melos? Add a README badge to show it off:

melos

[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos)

License


  Built and maintained with 💛 by Invertase.

  Follow on Twitter


Libraries

melos
version.g