Melos

https://melos.invertase.dev
Admin
Melos is a CLI tool used to manage Dart and Flutter monorepos with multiple packages, providing...
Tokens:29,548
Snippets:414
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure pubGetArgs

Source: https://melos.invertase.dev/configuration/overview

Example of passing additional arguments to pub get during the bootstrap process.

```yaml
melos:
  command:
    bootstrap:
      pubGetArgs:
        - --no-precompile
```

--------------------------------

### Clean and bootstrap workspace

Source: https://melos.invertase.dev/commands/clean

Gives the workspace a 'fresh start' by cleaning and then bootstrapping.

```bash
melos clean
melos bootstrap
```

--------------------------------

### Example groupByType output

Source: https://melos.invertase.dev/configuration/overview

An example of how the CHANGELOG.md appears when groupByType is enabled.

```markdown
## 1.2.0

### Features

 - added user authentication.
 - implemented dark mode support.

### Bug Fixes

 - corrected issue with API call.
 - resolved UI glitch on iOS.
```

--------------------------------

### Example: basic and custom initialization

Source: https://melos.invertase.dev/commands/init

Shows basic initialization with a workspace name and a custom initialization with options for directory and packages.

```bash
# Basic initialization
melos init my_workspace

# Custom initialization with options
melos init my_workspace \
  --directory custom_dir \
  --packages "modules/*"
```

--------------------------------

### Install Melos globally with dart pub global activate

Source: https://melos.invertase.dev/getting-started

Run this command to install Melos as a global package so it can be used from anywhere on your system.

```bash
dart pub global activate melos
```

--------------------------------

### Configure packageFilters in scripts

Source: https://melos.invertase.dev/guides/migrations

Example of the new packageFilters configuration using camelCase.

```yaml
scripts:
  test:
    exec: dart test
    packageFilters:
      dirExists: test
```

--------------------------------

### Include packages with a specific directory using --dir-exists

Source: https://melos.invertase.dev/filters

Includes only packages where a specific directory exists inside the package. The example bootstraps packages with an example directory.

```bash
# Only bootstrap packages with an example directory
melos bootstrap --dir-exists="example"
```

--------------------------------

### Bootstrap Melos workspace

Source: https://melos.invertase.dev/getting-started

Run this command to bootstrap your project, which installs dependencies, syncs shared dependencies, and runs bootstrap lifecycle scripts.

```bash
melos bootstrap
```

--------------------------------

### Run melos bootstrap

Source: https://melos.invertase.dev/commands/bootstrap

Initializes the workspace and installs remaining package dependencies. Supports all Melos filtering flags. The alias `melos bs` is also available.

```bash
melos bootstrap
# or
melos bs
```

--------------------------------

### Define complex workflows with steps

Source: https://melos.invertase.dev/configuration/scripts

Example of using the steps property to execute multiple commands sequentially within a single script definition.

```yaml
scripts:
  pre-commit:
    description: pre-commit git hook script
    steps:
      - echo 'hello world'
      - format --output none --set-exit-if-changed
      - dart test --fail-fast .
```

--------------------------------

### Created directory structure

Source: https://melos.invertase.dev/commands/init

The command creates the following structure: melos.yaml, pubspec.yaml, packages/ (always created), and apps/ (created if confirmed during setup).

```text
<directory>/
├── melos.yaml    # Workspace configuration
├── pubspec.yaml  # Root package configuration
├── packages/     # Packages directory (always created)
└── apps/         # Apps directory (created if confirmed during setup)
```

--------------------------------

### Root pubspec.yaml for Melos 7.0.0

Source: https://melos.invertase.dev/guides/migrations

Example of the root pubspec.yaml file structure required for Melos 7.0.0 using pub workspaces.

```yaml
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

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

--------------------------------

### Include packages with a specific file using --file-exists

Source: https://melos.invertase.dev/filters

Includes only packages where a specific file exists in the package. The example bootstraps packages with a README.md file.

```bash
# Only bootstrap packages with an README.md file
melos bootstrap --file-exists="README.md"
```

--------------------------------

### Include packages by name glob with --scope

Source: https://melos.invertase.dev/filters

Includes only packages with names matching the given glob. This option can be repeated. The example runs `flutter build ios` on all packages with "example" in the package name.

```bash
# Run `flutter build ios` on all packages with "example" in the package name
melos exec --scope="*example*" -- flutter build ios
```

--------------------------------

### Configure stdio: inherit for interactive scripts

Source: https://melos.invertase.dev/configuration/scripts

Example of setting stdio to inherit, which allows interactive commands like tmux to connect directly to the terminal.

```yaml
scripts:
  attach:
    run: tmux attach -t my_session
    stdio: inherit
```

--------------------------------

### Filter packages by category with --category

Source: https://melos.invertase.dev/filters

Filters packages based on categories declared in the root `pubspec.yaml` file. The example runs `flutter build ios` on all packages in the "examples" category.

```bash
# Run `flutter build ios` on all packages in the "examples" category.
melos exec --category="examples" -- flutter build ios
```

--------------------------------

### Configure preCommit hook

Source: https://melos.invertase.dev/commands/version

Example configuration for the preCommit hook in melos.yaml, which runs before the version commit is created.

```yaml
command:
  version:
    hooks:
      preCommit: |
        # Make changes to the version commit here.
        # You need to stage changes that you make yourself.
```

--------------------------------

### Basic exec command usage

Source: https://melos.invertase.dev/commands/exec

Executes an arbitrary command in each package. The command is run in a shell: `cmd.exe` on Windows, `sh` on other platforms. Example shows running `pub global run tuneup check`.

```bash
melos exec
# e.g. melos exec -- pub global run tuneup check
```

--------------------------------

### Git dependency reference

Source: https://melos.invertase.dev/guides/automated-releases

Example of a git dependency in pubspec.yaml using a specific version tag as a reference.

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

--------------------------------

### Expand filtered packages to include transitive dependencies with --include-dependencies

Source: https://melos.invertase.dev/filters

Takes the filtered list of packages and expands them to include those packages' transitive dependencies (ignoring filters). The example lists packages with scope some_package and includes dependencies.

```bash
melos list --scope=some_package --include-dependencies
```

--------------------------------

### Expand filtered packages to include transitive dependents with --include-dependents

Source: https://melos.invertase.dev/filters

Takes the filtered list of packages and expands them to include those packages' transitive dependents (ignoring filters). The example lists packages with scope some_package and includes dependents.

```bash
melos list --scope=some_package --include-dependents
```

--------------------------------

### Filter packages by git diff with --diff

Source: https://melos.invertase.dev/filters

Filters packages based on whether there were changes between a commit and the current HEAD or within a range of commits. A range can be specified using git shorthand syntax `<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`. The example runs `flutter build ios` on packages that are different between the current branch and a specified commit hash, and between remote `main` branch and HEAD.

```bash
# Run `flutter build ios` on all packages that are different between current
# branch and the specified commit hash.
melos exec --diff=<commit hash> -- flutter build ios

# Run `flutter build ios` on all packages that are different between remote
# `main` branch and HEAD.
melos exec --diff=origin/main...HEAD -- flutter build ios
```

--------------------------------

### melos version --manual-version for multiple packages with short form

Source: https://melos.invertase.dev/guides/automated-releases

Use --manual-version (or -V) to manually version multiple packages. Automatic versioning still applies to other packages; use --ignore '*' to exclude all from automatic. The comment line # Same but with short version is part of the example.

```sh
melos version --manual-version <package-1-name>:<version-change> --manual-version <package-2-name>:<version-change>
# Same but with short version
melos version -V <package-1-name>:<version-change> -V <package-2-name>:<version-change>
```

--------------------------------

### Bootstrap after initialization

Source: https://melos.invertase.dev/commands/init

After initialization, you can bootstrap your workspace by running these commands.

```bash
cd <directory>
melos bootstrap
```

--------------------------------

### Legacy select-package configuration

Source: https://melos.invertase.dev/guides/migrations

The previous configuration format using select-package and kebab-case.

```yaml
scripts:
  test:
    exec: dart test
    select-package:
      dir-exists: test
```

--------------------------------

### Show parsable output with --parsable

Source: https://melos.invertase.dev/commands/changed

Outputs the list in a parsable format instead of a columnified view.

```bash
melos changed --parsable
melos changed -p
```

--------------------------------

### Use --git-tag-version flag

Source: https://melos.invertase.dev/commands/version

Create a git tag for the version. Defaults to true.

```bash
melos version --git-tag-version
melos version -t
```

--------------------------------

### Recommended workspace directory structure

Source: https://melos.invertase.dev/getting-started

Shows the recommended directory structure for a Melos workspace, with apps and packages subdirectories and a root pubspec.yaml.

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

--------------------------------

### Custom commit message template

Source: https://melos.invertase.dev/configuration/overview

Example of overriding the default commit message template using YAML configuration.

```yaml
command:
  version:
    message: |
      chore: cut package releases 🎉

      {new_package_versions}
```

--------------------------------

### Use --prerelease flag

Source: https://melos.invertase.dev/commands/version

Version packages as a prerelease. Cannot be combined with the graduate flag.

```bash
melos version --prerelease
melos version -p
```

--------------------------------

### Dependency Overrides Marker Comment

Source: https://melos.invertase.dev/configuration/overview

Example of the marker comment used by Melos to manage dependency overrides in pubspec_overrides.yaml.

```yaml
# melos_managed_dependency_overrides: my_pkg
dependency_overrides:
  my_pkg:
    path: ../external_project/packages/my_pkg
```

--------------------------------

### List local packages

Source: https://melos.invertase.dev/commands/list

Lists information about the local packages in the workspace.

```bash
melos list
```

--------------------------------

### Version all packages including private ones

Source: https://melos.invertase.dev/commands/version

Use the --all or -a flag to include private packages that are typically skipped during the versioning process.

```bash
melos version --all
melos version -a
```

--------------------------------

### List packages as JSON

Source: https://melos.invertase.dev/commands/list

Outputs package information as a JSON array using the --json flag.

```bash
melos list --json
```

--------------------------------

### Set concurrency to 1

Source: https://melos.invertase.dev/commands/exec

Limits the maximum number of packages executing the command at any one time. Defaults to 5. This example sets concurrency to 1.

```bash
# Set a 1 concurrency
melos exec -c 1  -- "dart analyze ."
```

--------------------------------

### List packages with parsable output

Source: https://melos.invertase.dev/commands/list

Displays output in a parsable format instead of a columnified view using the --parsable or -p flag.

```bash
melos list --parsable
melos list -p
```

--------------------------------

### Run melos analyze with --no-pub

Source: https://melos.invertase.dev/commands/analyze

Skips the implicit pub get command before analysis for Flutter packages. This flag has no effect on Dart-only packages.

```bash
melos analyze --no-pub
```

--------------------------------

### Basic usage: melos init [workspace_name]

Source: https://melos.invertase.dev/commands/init

Initializes a new Melos workspace. If no workspace name is provided, you'll be prompted to enter one, defaulting to the current directory name.

```bash
melos init [workspace_name]
```

--------------------------------

### Generate release URL arguments

Source: https://melos.invertase.dev/guides/automated-releases

Commands to generate a prefilled release creation page link during the versioning process.

```sh
melos version --release-url
melos version -r
```

--------------------------------

### Add a script to run build_runner across packages

Source: https://melos.invertase.dev/getting-started

Add a script item to your root pubspec.yaml to run a command across all packages. This example runs dart run build_runner build in packages that depend on build_runner.

```yaml
name: my_workspace

...

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

--------------------------------

### Melos post bootstrap hook in pubspec.yaml

Source: https://melos.invertase.dev/commands/bootstrap

Add a post hook under melos.command.bootstrap.hooks in the root pubspec.yaml to run a command after melos bootstrap. The example runs 'dart pub run build_runner build' to generate files automatically.

```yaml
# root pubspec.yaml
# ...
melos:
  command:
    bootstrap:
      hooks:
        post: dart pub run build_runner build
# ...
```

--------------------------------

### Specify directory with --directory (-d)

Source: https://melos.invertase.dev/commands/init

Specifies the directory where the workspace should be created. If not provided, you'll be prompted to enter one. Defaults to the workspace name, or current directory ('.') if the workspace name matches the current directory name.

```bash
melos init my_workspace --directory custom_dir
```

--------------------------------

### Use --output flag

Source: https://melos.invertase.dev/commands/format

Allows reviewing formatting changes without overwriting files directly.

```bash
melos format --output
# or
melos format --o
```

--------------------------------

### List files to be formatted

Source: https://melos.invertase.dev/commands/format

Lists files that would be formatted without showing content or applying changes.

```bash
melos format -o none
```

--------------------------------

### Exclude packages by name glob with --ignore

Source: https://melos.invertase.dev/filters

Excludes packages with names matching the given glob. This option can be repeated. The example runs `flutter build ios` on all packages but ignores those whose package names contain "internal".

```bash
# Run `flutter build ios` on all packages but ignore those whose packages names contain "internal"
melos exec --ignore="*internal*" -- flutter build ios
```

--------------------------------

### Enable smart dependents with --smart-dependents

Source: https://melos.invertase.dev/commands/version

Only bumps dependent package versions when declared SemVer constraints do not allow the updated version. Defaults to off.

```bash
melos version --smart-dependents
```

--------------------------------

### Include packages depending on specific dependencies with --depends-on

Source: https://melos.invertase.dev/filters

Includes only packages that depend on specific dependencies. The example runs `flutter test` on packages that depend on both "flutter" and "firebase_core". Use --no-depends-on to filter packages that do not depend on the given dependencies.

```bash
melos exec --depends-on="flutter" --depends-on="firebase_core" -- flutter test
```

--------------------------------

### Show extended information with --long

Source: https://melos.invertase.dev/commands/changed

Displays verbose information about the changed packages.

```bash
melos changed --long
melos changed -l
```

--------------------------------

### Create root pubspec.yaml for workspace

Source: https://melos.invertase.dev/getting-started

Create this pubspec.yaml at the workspace root to define the workspace and its packages. The workspace field lists the paths to your packages.

```yaml
name: my_project
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package
  - packages/server_package
```

--------------------------------

### Publish packages to pub.dev

Source: https://melos.invertase.dev/commands/publish

Run the publish command. Dry-run is enabled by default, so this validates without publishing.

```bash
melos publish
```

--------------------------------

### Publish lifecycle hooks configuration

Source: https://melos.invertase.dev/commands/publish

Defines `pre` and `post` hooks in root `pubspec.yaml`. Pre runs before publish, post after; both run once even for multiple packages and during dry-run.

```yaml
# root pubspec.yaml
# ...
melos:
  command:
    publish:
      hooks:
        pre: dart pub run build_runner build
        post: dart pub run build_runner clean
# ...
```

--------------------------------

### Use --graduate flag

Source: https://melos.invertase.dev/commands/version

Graduate current prerelease versioned packages to stable versions. Cannot be combined with the prerelease flag.

```bash
melos version --graduate
melos version -g
```

--------------------------------

### List all scripts

Source: https://melos.invertase.dev/commands/run

Displays all scripts defined in the Melos workspace.

```bash
melos run --list
```

--------------------------------

### Enable useRootAsPackage in pubspec.yaml

Source: https://melos.invertase.dev/guides/migrations

Configuration to maintain repository root as a package in Melos 7.0.0 by enabling the useRootAsPackage option.

```yaml
# pubspec.yaml
name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package

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

--------------------------------

### Show dependency graph in Mermaid

Source: https://melos.invertase.dev/commands/changed

Outputs the dependency graph as a Mermaid diagram.

```bash
melos changed --mermaid
```

--------------------------------

### Define an exec script with options

Source: https://melos.invertase.dev/configuration/scripts

Configure exec as an object to provide specific options like concurrency alongside the command.

```yaml
scripts:
  hello:
    exec:
      command: echo 'Hello $(dirname $PWD)'
      concurrency: 1
```

--------------------------------

### Show dependency graph in Graphviz

Source: https://melos.invertase.dev/commands/changed

Outputs the dependency graph in the Graphviz DOT language.

```bash
melos changed --gviz
```

--------------------------------

### Enable useRootAsPackage in melos.yaml

Source: https://melos.invertase.dev/configuration/overview

Configures the workspace to treat the root directory as a package and defines categories for the root and sub-packages.

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

--------------------------------

### Compare against commit or tag

Source: https://melos.invertase.dev/commands/changed

Compares package changes against a specific commit hash or version tag.

```bash
melos changed v1.2.0
melos changed 4ba1b8f
```

--------------------------------

### Run a script with --no-select

Source: https://melos.invertase.dev/commands/run

Skips the package selection prompt while still applying packageFilters defined in the script configuration.

```bash
melos run <name> --no-select
```

--------------------------------

### Workspace-wide pubServer configuration

Source: https://melos.invertase.dev/commands/publish

Sets the server in `melos.yaml` under `command/publish` so it applies to all invocations. The CLI `--server` flag takes precedence.

```yaml
# melos.yaml
command:
  publish:
    pubServer: https://pub.flutter-io.cn
```

--------------------------------

### Configure dependencyOverridePaths

Source: https://melos.invertase.dev/configuration/overview

Configuration for linking external local packages into the workspace using glob patterns.

```yaml
melos:
  command:
    bootstrap:
      dependencyOverridePaths:
        - '../external_project/packages/**'
```

--------------------------------

### Supported 8.0.0 exec script configuration

Source: https://melos.invertase.dev/guides/migrations

In 8.0.0, use the command key within the exec block to pass options to scripts running across multiple packages.

```yaml
# After
scripts:
  test:
    exec:
      command: dart test --concurrency=1
      concurrency: 1
```

--------------------------------

### Publish to a custom server

Source: https://melos.invertase.dev/commands/publish

Forwards `--server <url>` to `dart pub publish`, overriding the `publish_to` field in `pubspec.yaml`.

```bash
melos publish --no-dry-run --server https://pub.flutter-io.cn
```

--------------------------------

### Run a script by name

Source: https://melos.invertase.dev/commands/run

Executes a script defined in the workspace root pubspec.yaml configuration.

```bash
melos run <name>
```

--------------------------------

### Output as JSON

Source: https://melos.invertase.dev/commands/changed

Formats the output as a JSON array.

```bash
melos changed --json
```

--------------------------------

### Publish with dry-run control

Source: https://melos.invertase.dev/commands/publish

Shows `--dry-run` (default) and `--no-dry-run` to actually publish.

```bash
# Publish packages with dry run
melos publish --dry-run

# Publish packages without dry run
melos publish --no-dry-run
```

--------------------------------

### List all scripts in JSON format

Source: https://melos.invertase.dev/commands/run

Outputs the list of defined scripts in JSON format.

```bash
melos run --list --json
```

--------------------------------

### Configure pre and post hooks for bootstrap command

Source: https://melos.invertase.dev/configuration/scripts

Hooks are defined in the hooks section of a command's configuration within the root pubspec.yaml file.

```yaml
command:
  bootstrap:
    hooks:
      pre: echo `bootstrap command is running...`
      post: echo `bootstrap command is done`
```

--------------------------------

### Group logs per package

Source: https://melos.invertase.dev/commands/exec

Buffers output per package and prints it once all packages finish, grouped and in order. Failed packages are printed last. Only effective with multiple packages and concurrency > 1; otherwise it is a no-op.

```bash
# Print the output grouped per package, once all packages have finished
melos exec --group-logs -- "dart analyze ."
```

--------------------------------

### Add git tags on publish

Source: https://melos.invertase.dev/commands/publish

Only creates tags when `--no-dry-run` is set. Usually not needed if `melos version` is used.

```bash
melos publish --no-dry-run --git-tag-version
```

--------------------------------

### Run melos changed

Source: https://melos.invertase.dev/commands/changed

Lists local packages that have changed since their latest release tag.

```bash
melos changed
```

--------------------------------

### Unsupported 8.0.0 exec script configuration

Source: https://melos.invertase.dev/guides/migrations

The legacy format for configuring exec scripts where run and exec were used together is no longer supported.

```yaml
# Before (no longer supported)
scripts:
  test:
    run: dart test --concurrency=1
    exec:
      concurrency: 1
```

--------------------------------

### Add Melos as dev dependency

Source: https://melos.invertase.dev/getting-started

Run this command to add Melos as a development dependency to the workspace root pubspec.yaml.

```bash
dart pub add melos --dev
```

--------------------------------

### Chaining commands with &&

Source: https://melos.invertase.dev/commands/exec

Runs multiple commands sequentially, stopping if any command fails. Pass multiple commands as a single string to `melos exec`; otherwise only the first command is executed.

```shell
melos exec -- "melos bootstrap && melos run build"
```

--------------------------------

### Run melos analyze with --no-fatal-warnings

Source: https://melos.invertase.dev/commands/analyze

Configures the command to ignore warnings, allowing the analysis to complete successfully even if warnings are present.

```bash
melos analyze --no-fatal-warnings
```

--------------------------------

### Configure self-hosted repository

Source: https://melos.invertase.dev/configuration/overview

Specifies the repository location for self-hosted instances by providing the type, origin, owner, and name.

```yaml
melos:
  repository:
    type: gitlab
    origin: https://gitlab.example.dev
    owner: invertase
    name: melos
```

--------------------------------

### List packages with extended information

Source: https://melos.invertase.dev/commands/list

Shows extended or verbose information about packages using the --long or -l flag.

```bash
melos list --long
melos list -l
```

--------------------------------

### Run melos format

Source: https://melos.invertase.dev/commands/format

Executes the default formatting command for the Melos workspace.

```bash
melos format
```

--------------------------------

### Define an extended workspace script

Source: https://melos.invertase.dev/configuration/scripts

The extends syntax allows for additional configuration including a custom name, description, and environment variables.

```yaml
scripts:
  hello:
    name: hey
    description: Greet the world
    run: echo "$GREETING World"
    env:
      GREETING: 'Hey'
```

--------------------------------

### Define a simple workspace script

Source: https://melos.invertase.dev/configuration/scripts

A basic script definition using the simple syntax where only the script name and command are specified.

```yaml
melos:
  scripts:
    hello: echo 'Hello World'
```

--------------------------------

### List packages with relative paths

Source: https://melos.invertase.dev/commands/list

Prints package paths relative to the root of the workspace using the --relative or -r flag.

```bash
melos list --relative
melos list -r
```

--------------------------------

### Use --changelog flag

Source: https://melos.invertase.dev/commands/version

Update CHANGELOG.md files based on conventional commit messages. Defaults to true.

```bash
melos version --changelog
melos version -c
```

--------------------------------

### Run melos version

Source: https://melos.invertase.dev/commands/version

Automatically version and generate changelogs for all packages. Supports all Melos filtering flags.

```bash
melos version
```

--------------------------------

### Configure pub timeouts and retries

Source: https://melos.invertase.dev/configuration/overview

Sets the per-request timeout and retry logic for pub registry interactions. Defaults are no timeout and 8 attempts with a 200ms base delay.

```yaml
melos:
  pub:
    timeoutSeconds: 60        # optional per-request timeout; 0/omit = no timeout
    retry:
      delayFactorMillis: 200  # base delay; doubled each retry
      randomizationFactor: 0.25
      maxDelaySeconds: 30
      maxAttempts: 8          # includes the first attempt
```
Tokens:
Raw