Use Melos to manage multi-package Flutter projects

Brother Cat said

The news client code template I am writing is just suitable for lightweight single-package projects with up to 100 pages.

But if there are more pages, it means that your project's business, functions, and components are complex enough, the project is huge, and there are many people involved. In this case, the project requires a multi-package architecture, and friends who have done android can understand it best.

This article is about how to use melos to manage multi-package projects, and see if it helps you.

Old iron remember to forward, Brother Mao will present more Flutter good articles~~~~

WeChat flutter training group ducafecat

original

Code

https://github.com/SAGARSURI/melos_demo

The integrate_melos branch is the completed code

reference

text

In most cases, when you create a flutter project. You use a package. This project consists of a pubspec.yaml, lib folder. You put all the features and utilities in the same package. But there are also projects that break down their features and utilities into multiple packages. This helps improve separation of concerns and allows the team to open source some of their software packages. Below is a schematic diagram of a multi-package project:

Here, we divide the project into three levels. The first level is the root project, which contains common configurations that apply to all the different packages in the project. The second layer has independent function packages, and they do not depend on each other. The third layer is composed of utility tool packages used in multiple function packages. I will not delve into how to create or structure a multi-package flutter project. This article will focus on solving the special challenges faced by a typical multi-package flutter project.

challenge

In a simple package, it is very simple to run the following tasks:

flutter pub get
flutter test
flutter analyze
Generating code coverage i.e flutter test --coverage

But running the same tasks in a multi-package flutter project is challenging, because you need to run these tasks in each package in the project and give a summary result after the task is completed. Now we know what the challenge is. Let us discuss possible ways to solve this problem.

solution

There are two possible solutions to solve this problem. Let's look at the first one:

Write bash scripts for various tasks

This is definitely a solution, but not a wise solution. You need to first write a script to find all the packages in the project and run one of the above tasks in it. You also need to ensure that the output is displayed in a beautiful format to make the content readable. If you prefer the GUI, then you need to create some kind of configuration in the IDE to run the script through the GUI

Integrate Melos into your project

This is a smarter solution than the first one I strongly recommend. So let us discuss in detail what Melos is and how to integrate it into your multi-package project

Introducing Melos

Melos is a CLI tool for managing flutter/dart projects with multiple packages.

Melos is created by a well-known group in the flutter community namely invertase. You can read detailed information about Melos on their website, but here is a quick list of the features Melos provides:

Automatic versioning & changelog generation. Automatic versioning & changelog generation.
Automated publishing of packages to automatically publish packages to pub.dev.
Local package linking and installation. Local package linking and installation
Executing simultaneous commands across packages. Executing simultaneous commands across packages
Listing of local packages & their dependencies. List of local packages & their dependencies.

Now let's see how to use Melos to perform all the above tasks.

Note: If you want to learn in practice, please download the introductory course. There is another branch where you can find the final version of the project.

https://github.com/SAGARSURI/melos_demo

Install Melos

Let's install Melos first. I assume that you have installed the Flutter SDK and set the Flutter and Dart paths to bash_profile . Run the following commands in the terminal:

dart pub global activate melos

The next step is to open the starter project in the IDE. I prefer to use Intellij and will show you some of the great GUI features provided by Melos. The project structure should be as follows:

Now create a file called melos.yaml and copy the following content into it:

name: melos_demo

packages:
  - utility/**
  - features/**
  - "*"

Let us understand the above script:
a) name: You must give the name of the project. You can find it in the pubspec.yaml of the root project.
b) packages: This list should contain the paths to individual packages in the project. Each path can be defined using the glob pattern expansion format.

Melos Bootstrap

Now, run the following command in the terminal from the root project to link all local packages together and update the dependencies, that is, flutter pub get.

melos bootstrap

After running the above command, you should see the following output:

You can read why you need to guide Melos here. To be precise, this is one of the important commands that should be executed when setting up Melos in a project or performing project cleanup.

https://docs.page/invertase/melos/getting-started#why-do-i-need-to-bootstrap

Melos Clean

You can execute this command when you want to delete temporary files (build artifacts, pub files, etc.) from the project. Here is what this command looks like:

melos clean

Commands

Now, you will set about creating different commands to achieve the tasks we mentioned at the beginning of this article.

To run test cases in a specific package, write the following commands in your melos.yaml file:

name: melos_demo

packages:
  - utility/**
  - features/**
  - "*"

scripts:
  test:selective_unit_test:
    run: melos exec --dir-exists="test" --fail-fast -- flutter test --no-pub --coverage
    description: Run Flutter tests for a specific package in this project.
    select-package:
      flutter: true
      dir-exists: test

Let us understand what happened in the script above:

1) You have created a custom script, test: selective_unit_test. Once executed, it will display an option to select a unit test package you want to run.

Melos provides powerful filtering options to select packets that meet the filtering conditions. In the above script, you use - dir-exists="test" as the filter option. This will filter all packages composed of testfolder. You can find more filtering options on their website.

3)——If a failed test case is encountered, fail-fast will immediately terminate the script execution.

4) You can use the description section to provide a readable description for each script.

5) You must be wondering why you named this command test: selective_unit_test. The next command will answer your question.

6) You can read in detail what melos exec does. Basically, it will execute commands or scripts in every package in the project.

https://docs.page/invertase/melos/commands#exec

Now run the following command:

melos run test:selective_unit_test

You will see the following output:

The above command can find these packages that contain folder tests. Enter 2 as an option, and you will see the following output:

Run test cases in all packages Now write the following command, which will run all unit test cases in the project. This will not prompt the selection of any options:

scripts:
  test:
    run: melos run test:selective_unit_test --no-select
    description: Run all Flutter tests in this project.

Let's discuss what the above command does:

This command will basically run the previous command --no-select as an argument. This means to run all unit tests
You can use melos to run this command because there may be multiple variants of test commands, just like the one you created in the previous step ie test:selective_unit_test. You can also create more variants, such as test:e2e_test, test: bdd_test etc. You can combine all variables together and run test in one command ie.

Run analyzein in all packages: Create the following command in the script section:

analyze:
  run: melos exec -- flutter analyze .
  description: Run `dart analyze` in all packages.

There is nothing special here, you can execute the melos run analysis to run the analysis in all packages.

Generate code coverage for the entire project: Generate code coverage for the entire project. A custom script is included in the project, which is combined coverage. Shhh. This will basically merge all lcov.info files from different packages into one lcov.info file. Then, you can use this method to convert the lcov.info file to HTML.

https://stackoverflow.com/a/53663093/4161284

#!/usr/bin/env bash

escapedPath="$(echo `pwd` | sed 's/\//\\\//g')"

if grep flutter pubspec.yaml > /dev/null; then
  if [ -d "coverage" ]; then
    # combine line coverage info from package tests to a common file
    if [ ! -d "$MELOS_ROOT_PATH/coverage_report" ]; then
      mkdir "$MELOS_ROOT_PATH/coverage_report"
    fi
    sed "s/^SF:lib/SF:$escapedPath\/lib/g" coverage/lcov.info >> "$MELOS_ROOT_PATH/coverage_report/lcov.info"
    rm -rf "coverage"
  fi
fi

Write the following commands under the script section:

gen_coverage: melos exec -- "\$MELOS_ROOT_PATH/combine_coverage.sh"

Path will give the path where MELOS.yaml is stored, which is the root project. After the script is executed. You can see the coverage_report folder in the project. Now you have a lcov.info file, it will give you a report of the entire project.

In the end, your melos.yaml file looks like this:

name: melos_demo

packages:
  - utility/**
  - features/**
  - "*"
scripts:
  test:selective_unit_test:
    run: melos exec --dir-exists="test" --fail-fast -- flutter test --no-pub --coverage
    description: Run Flutter tests for a specific package in this project.
    select-package:
      flutter: true
      dir-exists: test

  test:
    run: melos run test:selective_unit_test --no-select
    description: Run all Flutter tests in this project.

  analyze:
    run: melos exec -- flutter analyze .
    description: Run `dart analyze` in all packages.

  gen_coverage: melos exec -- "\$MELOS_ROOT_PATH/combine_coverage.sh"

Graphical user interface options

If you don't want to execute these commands through the terminal and want to run them using the GUI, then Melos can meet your requirements. After adding all the commands, you can run the bootloader commands again. This will generate some configuration and you can see some graphical user interface options as follows: