melos 0.1.0-13.0.pre

Melos

🌋 A tool for managing Dart projects with multiple packages.


⚠️ Note: this project is still very early on in development.



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.

What does a Melos repo look like? #

There's actually very little to it. You have a file structure that looks like this:

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

What can Melos do? #

The two primary commands in Melos are melos bootstrap and melos publish.

  • bootstrap will link local packages in the repo together and install any remaining package dependencies.
  • publish will help publish any updated packages.
    • ⚠️ publish support is still a work in progress

Getting Started #

Let's start by installing Melos as a global package via Pub.

pub global activate melos

New Projects #

⚠️ init support is still a work in progress

To initialize a new Melos project run the following:

mkdir my-melos-repo && cd $_
melos init

This will create a melos.yaml configuration file as well as a packages folder, so your folder should now look like this:

my-melos-repo/
  packages/
  melos.yaml

Existing Projects #

To use Melos in an existing monorepo create a melos.yaml file in the root ofr your project.

Sample file:

name: flutterfire

packages:
  - packages/**

scripts:
  analyze: melos exec -- pub global run tuneup check
  postbootstrap: tuneup --version || pub global activate tuneup
  postclean: melos exec -- rm -rf ./build ./android/.gradle ./ios/.symlinks ./ios/Pods ./android/.idea ./.idea

dev_dependencies:
  pedantic: ^1.8.0

Commands #

Full commands list and args can be viewed by running melos --help.


bootstrap

Initialize the workspace, link local packages together and install remaining package dependencies.

Supports all package filtering options.

Example:

melos bootstrap --ignore="*example*"

Output:

$ melos bootstrap
   └> /Users/mike/Documents/Projects/Flutter/ff_internal

Bootstrapping project...               SUCCESS
Linking project packages...            SUCCESS

Packages:
  • cloud_firestore
    └> ./packages/cloud_firestore/cloud_firestore
  • cloud_firestore_platform_interface
    └> ./packages/cloud_firestore/cloud_firestore_platform_interface
  • cloud_firestore_web
    └> ./packages/cloud_firestore/cloud_firestore_web
  • cloud_functions
    └> ./packages/cloud_functions/cloud_functions
  • cloud_functions_example

...

 -> 39 plugins bootstrapped

clean

Clean this workspace and all packages. This deletes the temporary pub files such as ".packages" & ".flutter-plugins"

Example:

melos clean

exec

Run a script by name defined in the workspace melos.yaml config file.

Example: Running tuneup analyzer in all packages

melos exec -- pub global run tuneup check

Output:

$ melos exec --
   └> pub global run tuneup check
       └> RUNNING (in 39 packages)

[cloud_firestore]: Checking project cloud_firestore...
[cloud_firestore_platform_interface]: Checking project cloud_firestore_platform_interface...
[cloud_functions_example]: Checking project cloud_functions_example...
[cloud_firestore_web]: Checking project cloud_firestore_web...
[cloud_functions]: Checking project cloud_functions...
...

run

Execute an arbitrary command in each package.

Example: Running a script named analyze that is defined in melos.yaml

melos run analyze

melos.yaml:

name: flutterfire
packages:
  - packages/**
scripts:
  analyze: melos exec -- pub global run tuneup check
  # ...

Output:

$ melos run analyze
   └> melos exec -- pub global run tuneup check
       └> RUNNING

$ melos exec --
   └> pub global run tuneup check
       └> RUNNING (in 39 packages)

[cloud_firestore]: Checking project cloud_firestore...
[cloud_functions_example]: Checking project cloud_functions_example...
[cloud_firestore_platform_interface]: Checking project cloud_firestore_platform_interface...
[cloud_firestore_web]: Checking project cloud_firestore_web...
[cloud_functions]: Checking project cloud_functions...

...

Lerna #

This project is heavily inspired by Lerna.

README Badge #

Using Melos? Add a README badge to show it off:

melos

[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos)

License #


Built and maintained with 💛 by Invertase.

Chat on Discord Follow on Twitter


Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate melos

2. Use it

The package has the following executables:


$ melos

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  melos: ^0.1.0-13.0.pre

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:melos/melos.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
65
Overall:
Weighted score of the above. [more]
43
Learn more about scoring.

We analyzed this package on May 30, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.2
  • pana: 0.13.8-dev

Health issues and suggestions

Document public APIs. (-1 points)

1 out of 1 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Fix lib/src/pub/pub_file_flutter_plugins.dart. (-0.50 points)

Analysis of lib/src/pub/pub_file_flutter_plugins.dart reported 1 hint:

line 4 col 8: Unused import: '../common/utils.dart'.

Format lib/src/common/package.dart.

Run dartfmt to format lib/src/common/package.dart.

Format lib/src/common/workspace.dart.

Run dartfmt to format lib/src/common/workspace.dart.

Maintenance issues and suggestions

Provide a file named CHANGELOG.md. (-20 points)

Changelog entries help developers follow the progress of your package. See the example generated by stagehand.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and melos.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.2 <3.0.0
args ^1.6.0 1.6.0
cli_util ^0.1.4 0.1.4
collection ^1.14.12 1.14.12
glob ^1.2.0 1.2.0
meta ^1.1.8 1.1.8
path ^1.7.0 1.7.0
pool ^1.4.0 1.4.0
prompts ^1.3.1 1.3.1
pub_semver ^1.4.4 1.4.4
string_scanner ^1.0.5 1.0.5
yaml ^2.2.1 2.2.1
yamlicious ^0.1.0 0.1.0
Transitive dependencies
async 2.4.1
charcode 1.1.3
io 0.3.4
js 0.6.1+1
matcher 0.12.6
node_interop 1.1.1
node_io 1.1.1
quiver 2.1.3
source_span 1.7.0
stack_trace 1.9.3
term_glyph 1.1.0
Dev dependencies
pedantic ^1.9.0 1.9.0