Melos requires a few one-off steps to be completed before you can start using it.
Install Melos as a global package via pub.dev so it can be used from anywhere on your system:
dart pub global activate melos
Setup a workspace#
Melos is designed to work with a workspace. A workspace is a directory which
contains all the packages that are going to be developed together. Its root
directory must contain a
Install Melos in the workspace#
Different Melos workspaces might use different versions of Melos. To ensure
everyone working in the workspace (as well as CI jobs) is using the same version
of Melos, a dependency on the
melos package has to be added to the
pubspec.yaml file at the workspace root directory. The globally installed
version of Melos will switch to the version specified in the
file, if both versions are not the same.
If you don't have a
pubspec.yaml file at the workspace root yet, create one
name: <project>_workspace environment: sdk: '>=2.18.0 <3.0.0'
pubspec.lock file should also be committed. Make sure to
exclude it from the
Add Melos as a development dependency by running the following command:
dart pub add melos --dev
Configure the workspace#
Next create a
melos.yaml file at the repository root. Within the
file, add the
name: <project> packages: - packages/*
packages list should contain paths to the individual packages within your
project. Each path can be defined using the
glob pattern expansion format.
pubspec_overrides.yaml files to link local packages for
development. Typically these files should be ignored by git. To ignore these
files, add the following to your
Once installed & setup, Melos needs to be bootstrapped. Bootstrapping has 2 primary roles:
- Installing all package dependencies (internally using
- Locally linking any packages together.
Why do I need to bootstrap?#
In normal projects, packages can be linked by providing a
path within the
pubspec.yaml. This works for small projects however presents a problem at
scale. Packages cannot be published with a locally defined path, meaning once
you're ready to publish your packages you'll need to manually update all the
pubspec.yaml files with the versions. If your packages are also
tightly coupled (dependencies of each other), you'll also have to manually check
which versions should be updated. Even with a few packages this can become a
long and error-prone task.
Melos solves this problem by overriding local files which the Dart analyzer uses
to read packages from. If a local package exists (defined in the
file) and a different local package has it listed as a dependency, it will be
linked regardless of whether a version has been specified.
Once successfully bootstrapped, you can develop your packages side-by-side with changes to a single package immediately reflecting across other dependent packages.
Melos also provides other helpful features such as running scripts across all
packages. For example, to run dart analyzer in each package, add a new
item in your
name: my_project packages: - packages/** scripts: analyze: exec: dart analyze .
Then execute the command by running
melos run analyze.
If you're looking for some inspiration as to what scripts can help with, check out the FlutterFire repository.
If you are using VS Code, there is an extension available, to integrate Melos with VS Code.