Melos

<p align="center"> <a href="https://melos.invertase.dev/~melos-latest"> <img src="https://static.invertase.io/assets/melos-logo.png" alt="Melos" /> <br /><br /> </a> <span>A tool for managing Dart projects with multiple packages, inspired by <a href="https://lerna.js.org">Lerna</a>.</span> </p> <p align="center"> <a href="https://github.com/invertase/melos#readme-badge"><img src="https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square" alt="Melos" /></a> <a href="https://docs.page"><img src="https://img.shields.io/badge/powered%20by-docs.page-34C4AC.svg?style=flat-square" alt="docs.page" /></a> <a href="https://invertase.link/discord"> <img src="https://img.shields.io/discord/295953187817521152.svg?style=flat-square&colorA=7289da&label=Chat%20on%20Discord" alt="Chat on Discord"> </a> </p> <p align="center"> <a href="https://melos.invertase.dev/~melos-latest">Documentation</a> &bull; <a href="https://github.com/invertase/melos/blob/main/LICENSE">License</a> </p>

---

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.

Migrate to Melos 7.x.x

Since the pub workspaces feature has been released, Melos has been updated to rely on that, instead of creating pubspec_overrides.yaml files and thus some migration is needed.

The main difference for migration is that the melos.yaml file no longer exists, only the root pubspec.yaml file.

To migrate to Melos 7.x.x a few steps are needed:

1. Start with running melos clean to remove all the pubspec_overrides.yaml entries and then continue with moving all your content.
2. Add resolution: workspace to all of your packages' pubspec.yaml files.
3. Add a list of all your packages to the root pubspec.yaml file, under the workspace key.
4. Move all the content from your melos.yaml file to the root pubspec.yaml file, under the melos key. (Note that the packages list is no longer needed as it is replaced with the workspace list.)

[!NOTE] The workspace list doesn't support globs yet, so you have to list all your packages manually. Give a thumbs up here so that the team can prioritize this feature.

[!NOTE] Root packages migration: If your existing project uses the repository root as a package, you can enable useRootAsPackage: true in the melos configuration to maintain this behavior, or restructure your project to move the main application to a subdirectory. See the Configuration Overview for details.

After the migration, your root pubspec.yaml file would now look something like this:

name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package
  - packages/server_package
dev_dependencies:
  melos: ^7.0.0-dev.9

melos:
  # All of the content of your previous melos.yaml file
  # (Except for the packages and name)

And this is what the pubspec.yaml file of a package would look like:

name: my_package
environment:
  sdk: ^3.9.0
resolution: workspace

[!NOTE] You have to use Dart SDK 3.6.0 or newer to use pub workspaces.

Github Action

If you're planning on using Melos in your GitHub Actions workflows, you can use the Melos Action to run Melos commands, this action also supports automatic versioning and publishing directly from your workflows.

What does a Melos workspace look like?

A default file structure looks something like this:

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

The location of your packages needs be configured via the workspace section in your root pubspec.yaml file, see the pub workspaces documentation for more information.

What can Melos do?

• 🔗 Link local packages in your workspace together without adding dependency overrides (achieved by pub workspaces).
• 📦 Automatically version, create changelogs and publish your packages using Conventional Commits.
• 📜 Pre-define advanced custom scripts for your workspace in your root pubspec.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.
  • Scripts can even prompt to select a package to run against with pre-defined filters.
• ⚡ 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.
  • --diff=<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.
  • --include-dependencies
    • Expands the filtered list of packages to include those packages' transitive dependencies (ignoring filters).
  • --include-dependents
    • Expands the filtered list of packages to include those packages' transitive dependents (ignoring filters).
• ♨️ Advanced support for IntelliJ IDEs with automatic creation of run configurations for workspace defined scripts and more on workspace bootstrap.
  • Integration with VS Code through an [extension][melos-code].

Getting Started

Go to the Getting Started page of the documentation to start using Melos.

Who is using Melos?

The following projects are using Melos:

• firebase/flutterfire
• Flame-Engine/Flame
• fluttercommunity/plus_plugins
• GetStream/stream-chat-flutter
• canonical/ubuntu-desktop-provision
• ubuntu/app-center
• 4itworks/opensource_qwkin_dart
• gql-dart/ferry
• cbl-dart/cbl-dart
• ema987/paddinger
• flutter-stripe/flutter_stripe
• danvick/flutter_form_builder
• kmartins/groveman
• flutternetwork/WiFiFlutter
• iapicca/yak_packages
• atsign-foundation/at_app
• sub6resources/flutter_html
• ferraridamiano/ConverterNOW
• rrifafauzikomara/youtube_video
• mobxjs/mobx.dart
• NetGlade/auto_mappr
• myConsciousness/atproto.dart
• GrowERP Flutter ERP
• mrverdant13/coverde
• ThexXTURBOXx/flutter_web_auth_2
• woltapp/wolt_modal_sheet
• [cfug/dio](https://gi