Getting Started

Melos requires a few one-off steps to be completed before you can start using it.

Pub Workspaces

First start by reading the short Pub Workspaces guide for how to get your monorepo ready to be used with Melos and Pub Workspaces, the guide can be found on the Dart website.

Installation

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 melos.yaml and a pubspec.yaml file.

Recommended directory structure

When using Melos you shouldn't have a project in the root of the workspace, since that is where the configuration for the workspace will live and those dependencies might clash with your project dependencies.

The following is the recommended workspace directory structure:

my_project
├── apps
│   ├── apps_1
│   └── apps_2
├── packages
│   ├── package_1
│   └── package_2
├── melos.yaml
├── pubspec.yaml
└── README.md

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 pubspec.yaml file, if both versions are not the same.

If you don't have a pubspec.yaml file at the workspace root yet, create one now:

name: my_project
publish_to: none
environment:
  sdk: ^3.6.0
workspace:
  - packages/helper
  - packages/client_package
  - packages/server_package

Where packages/helper, packages/client_package and packages/server_package are the paths to the packages in your workspace.

The corresponding pubspec.lock file should also be committed. Make sure to exclude it from the .gitignore file.

Add Melos as a development dependency by running the following command:

dart pub add melos --dev

Configure your packages

Next, in all your packages pubspec.yaml files, add the resolution: workspace field:

name: my_package
resolution: workspace

...

Configure the workspace

Next create a melos.yaml file at the repository root. Within the melos.yaml file, add the name and packages fields:

name: my_project

packages:
  - apps/**
  - packages/**

The packages list should contain paths to the individual packages within your project. Each path can be defined using the glob pattern expansion format.

Bootstrapping

Once installed & setup, Melos needs to be bootstrapped. Bootstrapping has three primary functions:

1. Installing all package dependencies (internally using pub get).
2. Syncing shared dependencies between packages.
3. Running any bootstrap lifecycle scripts.

Bootstrap your project by running the following command:

melos bootstrap

If you wonder why bootrapping is needed you can read more about it in the Bootstrap section.

Next steps

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 script item in your melos.yaml:

name: my_project

packages:
  - apps/**
  - packages/**

scripts:
  generate:
    run: melos exec -c 1 --depends-on build_runner -- dart run build_runner build

Then execute the command by running melos generate.

If you're looking for some inspiration as to what scripts can help with, check out the FlutterFire repository or the Flame repository.

If you are using VS Code, there is an extension available, to integrate Melos with VS Code.