Melos scripts
Scripts are defined under melos.scripts in the root pubspec.yaml and run
with melos run <name> or directly as melos <name>.
Guidelines
- The script name is the key in the
scriptsmap. There is nonamefield. - A script is either
run(runs once, in the workspace root) orexec(runs in every selected package throughmelos exec). Never set both. - To pass options to
exec, makeexeca map with the command undercommand. Do not put the command inrunnext to anexecmap, that is the Melos 7 format and Melos 8 rejects it. - Filter names in
packageFiltersare camel cased:dirExists,fileExists,dependsOn,noDependsOn,flutter,noPrivate,published,scope,ignore,category,diff,includeDependencies,includeDependents,postFilters. Never use kebab case or the oldselect-packagekey. - Scripts run in
sh(andcmd.exeon Windows). Chain commands with&&so that a failure stops the script. - Always add a
description; it is shown inmelos runand in generated IDE run configurations. - Hooks go under
command/<name>/hooks, not inscripts. The oldpostbootstrapandpostcleanscript names are not hooks anymore. - Reference
envandMELOS_*variables as$VARor${VAR}for cross-platform scripts. - In an
execscript, escape command substitutions that need the package variables, for example\$(basename $MELOS_PACKAGE_PATH), since an unescaped one runs once beforemelos execstarts. - A custom script with the same name as a built-in command overrides that
command, for both
melos <name>andmelos run <name>.
Script forms
melos:
scripts:
# Shorthand: name and command only.
hello: echo 'Hello World'
# Runs once in the workspace root.
prepare:
description: Bootstrap and generate code.
run: melos bootstrap && melos run generate
# Runs in every package, with the default exec options.
analyze:
description: Analyze every package.
exec: dart analyze .
# Runs in every package, with exec options.
test:
description: Run the tests of every package that has a test directory.
exec:
command: dart test
concurrency: 1
failFast: true
packageFilters:
dirExists: test
env:
CI: "true"
# Code generation, ordered by the dependency graph and skipped in packages
# whose sources did not change since the last successful run.
generate:
description: Generate code with build_runner.
exec:
command: dart run build_runner build --delete-conflicting-outputs
orderDependents: true
sources:
- lib/**.dart
- pubspec.yaml
packageFilters:
dependsOn: build_runner
exec options
command: the command, required whenexecis a map.concurrency: packages to run in at once. Defaults to the processor count.failFast: stop after the first failing package. Defaults tofalse.orderDependents: run in dependencies before dependents. Defaults tofalse. Required for scripts that generate files that matchsources.groupLogs: buffer the output and print it per package when all finished, failures last. Defaults tofalse.sources: globs relative to each package root. The script is skipped in packages where none of the matching files, or those of their workspace dependencies, changed since the last success. Checksums live in.dart_tool/melos/fingerprints.melos run <name> --run-unchangedruns everywhere anyway,--ignore-sourcesdisables the checksums.
Defaults for all exec scripts can be set under command/exec in the root
pubspec.yaml.
packageFilters with run
A run script always executes once. packageFilters on a run script only
sets MELOS_PACKAGES for the melos command that the script invokes, so it
scopes a nested melos exec. If the script does not call melos, the filters
only produce a package prompt and have no effect. Use exec to run a command
per package.
scripts:
analyze_lib:
run: melos exec -- dart analyze
packageFilters:
dirExists: lib
When a script has packageFilters, melos run prompts to select one package
or all of them. Skip the prompt with melos run <name> --no-select or set
command/run/noSelect: true.
Composition
scripts:
# Sequential steps. Each step is a script name or a shell command.
pre-commit:
description: Format, analyze and test.
steps:
- format --output none --set-exit-if-changed
- analyze
- test
# Dependency graph. Shared dependencies run once.
verify:
description: Generate once, then build and test.
dependsOn:
- build
- test
build:
run: dart run tool/build.dart
dependsOn:
- generate
test:
exec: dart test
dependsOn:
- generate
# Only reachable from steps or dependsOn, hidden from prompts.
generate:
exec: dart run build_runner build
private: true
# Scripts can be grouped for `melos run --group ci`.
lint:
exec: dart analyze .
groups:
- ci
steps and dependsOn cannot carry exec options or packageFilters; set
them on the individual scripts. dependsOn is not supported on hooks. Extra
arguments passed to melos run only reach the requested script.
Interactive scripts
Scripts are piped by default so Melos can prefix their output. A script that
needs a real terminal, such as flutter run with hot reload keys, must set
stdio: inherit. It cannot be combined with exec or steps.
scripts:
dev:
run: flutter run
stdio: inherit
Hooks
melos:
command:
bootstrap:
hooks:
pre: echo "bootstrapping"
post: dart run build_runner build
clean:
hooks:
post: melos exec --flutter -- flutter clean
version:
hooks:
# Runs after pubspecs and changelogs are updated, before the version
# commit. Stage any files you change yourself.
preCommit: dart run tool/update_version_constant.dart && git add lib/version.dart
post: echo "versioned"
publish:
hooks:
pre: dart run build_runner build
post: dart run build_runner clean
bootstrap, clean, version and publish support pre and post.
version additionally supports preCommit. The publish hooks also run on a
dry run; check MELOS_PUBLISH_DRY_RUN to tell the two apart.
Environment variables
Available in melos exec and exec scripts: MELOS_ROOT_PATH,
MELOS_PACKAGE_NAME, MELOS_PACKAGE_VERSION, MELOS_PACKAGE_PATH, and for
example packages MELOS_PARENT_PACKAGE_NAME, MELOS_PARENT_PACKAGE_VERSION
and MELOS_PARENT_PACKAGE_PATH.
User settable: MELOS_PACKAGES (comma separated scope), MELOS_SDK_PATH,
MELOS_QUIET, MELOS_RUN_UNCHANGED, MELOS_IGNORE_SOURCES,
MELOS_ANSI_STYLES.
From a terminal, quote the command so that the outer shell does not expand the package variables first:
melos exec -- 'echo $MELOS_PACKAGE_NAME'
Reusing configuration with YAML anchors
Keys prefixed with x- are ignored by Melos and can hold anchors. YAML merge
keys (<<) are not supported, an alias replaces a whole value:
melos:
scripts:
x-analyze: &analyze
exec:
command: dart analyze .
concurrency: 1
analyze: *analyze
Anti-patterns
# Wrong: Melos 7 format, rejected by Melos 8.
test:
run: dart test
exec:
concurrency: 1
# Right
test:
exec:
command: dart test
concurrency: 1
# Wrong: kebab case and the removed select-package key.
test:
exec: dart test
select-package:
dir-exists: test
# Right
test:
exec: dart test
packageFilters:
dirExists: test
# Wrong: hooks as scripts (Melos 2 format).
scripts:
postbootstrap: dart run build_runner build
# Right
command:
bootstrap:
hooks:
post: dart run build_runner build