How to manage your Flutter monorepos
Tags: flutter, mobile, devops, dart
Published: 2022-08-05 09:19:56

> This article is written by **Nils Reichardt** and originally posted to [Codemagic blog](https://blog.codemagic.io/flutter-monorepos/).

Monorepos are extremely helpful when working with larger codebases. But they also come with additional management costs. In this article, we will go through the process of managing a monorepo with a tool like [Melos](https://github.com/invertase/melos) and set up our repository for CI/CD with [Codemagic](https://codemagic.io).

## Introduction to monorepos
Nowadays, many companies and projects use the structure of a monorepo. A few examples include [Flutter](https://github.com/flutter/flutter) itself, [FlutterFire](https://github.com/firebase/flutterfire) (a set of Flutter packages for Firebase), [Riverpod](https://github.com/rrousselGit/riverpod), [PlusPlugins](https://github.com/fluttercommunity/plus_plugins) by the Flutter community, and Very Good Ventures in projects like [I/O Photo Booth](https://github.com/flutter/photobooth).

But what is a monorepo? A monorepo is a single version-controlled repository that can store many different projects.

### Advantages of a monorepo
A monorepo has some useful advantages:

* **Code reuse**: A monorepo enables you to split your codebase into small independent packages, which is great for code reuse and testing
* **Better CI**: With a monorepo, you can easily trigger the CI when changing something else in your repository (for example, you can trigger Flutter integration tests when making changes to the back end)
* **Dependency management**: You have local packages without needing a dependency manager, like [pub.dev](https://pub.dev)
* **Enforces layered architecture**: You can require yourself and your team to apply a layered architecture by splitting the layers into multiple packages
* **Keeps everything stored in one place**: New developers simply clone the monorepo and have everything in one repository

### Disadvantages of a monorepo
Like everything in life, a monorepo does have some disadvantages:

* **More overhead**: You need to set up tools to manage the repository
* **No per-project access control:** When you have everything in one repository, everyone with repository access can access everything

_Note:_ These are just a few of the advantages and disadvantages of a monorepo. There are many more things to consider when comparing a monorepo and multirepos.

## Scope of this article
Now that you have a basic understanding of a monorepo, let’s set the scope for this article since monorepos are a big topic. You can store your front end, back end, internal tools, website, and more in your monorepo. Google is known for having the largest codebase in the world — they have everything in one repository. So covering everything about monorepos in one article would be too much.

This article will focus specifically on Flutter/Dart monorepos, which involve splitting your app into small independent packages.

### Example app
To provide a practical example, we are using the Flutter counter app with a few adjustments.

![Counter app screenshot](https://blog.codemagic.io/uploads/2022/07/CounterAppScreenshot.png)

```
apps/
  counter_app
packages/
  counter_widgets
  counter_lint
```

In `apps`, we have apps that we actually deploy. We could also have an internal app, website, etc.

In `packages`, we have our local packages.

You can check out the full source [here](https://github.com/nilsreichardt/codemagic_monorepo_example).

## Tools
As just mentioned, tools are extremely helpful for managing your monorepo. You will face challenges such as the following:

* Getting the dependencies for all packages
* Checking linting for all packages
* Checking formatting for all packages
* Running tests for all packages
* Running `build_runner` in all packages
* Merge code coverage for all packages

You could write your own bash script or CLI to help manage these tasks. However, this costs you some time. In order to deal with these tasks more quickly, you can use community tools, like [Melos](https://github.com/invertase/melos), [Very Good CLI](https://github.com/VeryGoodOpenSource/very_good_cli), or [Sidekick](https://github.com/phntmxyz/sidekick). In this article, we are going to use Melos. Melos is also used by repositories like [FlutterFire](https://github.com/firebase/flutterfire), [AWS Amplify (Flutter)](https://github.com/aws-amplify/amplify-flutter), [Flame](https://github.com/flame-engine/flame), and [Plus Plugins](https://github.com/fluttercommunity/plus_plugins).

### Setting up Melos
First, you need to install Melos by running the following command in your terminal:

```sh
dart pub global activate melos
```

To configure Melos, we need to create a top-level `melos.yaml` file. The structure currently looks like this:

```
apps/
  counter_app
packages/
  counter_widgets
  counter_lint
melos.yaml
```

Now, we set up the `melos.yaml` file with a basic configuration:

```yaml
# The name of the project (required) is used for display purposes within IO environments and IDEs.
name: counter

# A list of paths to local packages that are included in the Melos workspace. Each entry can be a specific path or a glob pattern.
packages:
  - "apps/*"
  - "packages/**"

# Recommended option for projects with Dart 2.17.0 or greater.
#
# This enables a new mechanism for linking local packages, which integrates
# better with other tooling (e.g. dart tool, Flutter tool, IDE plugins) than the
# mechanism currently being used by default. Please read the documentation for
# usePubspecOverrides before enabling this feature.
#
# See https://melos.invertase.dev/getting-started#setup
command:
  bootstrap:
    usePubspecOverrides: true
```

After setting up the `melos.yaml` file, run the `bootstrap` command to initialize Melos for your project:

```sh
melos bootstrap
```

Bootstrapping has two primary roles:

1. Installing all package dependencies (internally using pub get)
2. Locally linking any packages together

In `melos.yaml`, we can also define our commands, which are executed in every Dart/Flutter package inside our defined Melos workspace.

```yaml
scripts:
  analyze:
    run: melos exec -- "flutter analyze"
    description: Run `flutter analyze` in all packages
  
  format:
    run: melos exec -- "flutter format . --set-exit-if-changed"
    description: Run `flutter format .` in all packages

  test:
    # Only run the test command when the package has a test directory
    run: melos exec --dir-exists=test -- "flutter test"
    description: Run `flutter test` in all packages
```

We are now able to execute our script with `melos run SCRIPT_NAME`. To run the `flutter analyze` command in all packages, we can use this command:

```sh
melos run analyze
```

You can add any script you want in the `melos.yaml` file, like the `build_runner`. Check out the Melos [documentation](https://melos.invertase.dev/configuration/scripts) to find out more about the `scripts` configuration.

Also, take a look at [melos-code](https://github.com/blaugold/melos-code), a VS Code extension for Melos that helps you to work with Melos and VS Code.

## Setting up your Flutter monorepo for CI/CD
You should be able to manage your monorepo locally with Melos. However, you might need to configure your CI/CD environment to fully support your monorepo. We are going to use [Codemagic](https://codemagic.io) as a CI/CD provider.

### Scope of our CI
Our CI pipeline should perform the following checks for every pull request:

* Run the `melos run analyze` command
* Run the `melos run format` command
* Run the `melos run test` command
* Upload the results of failed Golden tests

### Configure CI/CD for a monorepo
#### Set up Codemagic
First, you need a Codemagic account. If you don’t have one already, you can [sign up for Codemagic](https://codemagic.io/signup) with your Git provider. Set up Codemagic with the [Workflow Editor](https://docs.codemagic.io/flutter-configuration/flutter-projects/) or the [`codemagic.yaml`](https://docs.codemagic.io/yaml/yaml-getting-started/) file. If you need a step-by-step guide, you can follow [this article](https://blog.codemagic.io/flutter-golden-tests-with-codemagic-cicd/) to set up your monorepo for Codemagic.

The Workflow Editor is simple to use for a basic app. However, for a monorepo, it’s better to use `codemagic.yaml` because we can run our own commands with Melos. For this reason, this article only covers the setup for the `codemagic.yaml` file.

#### Set up Melos for CI/CD
Setting up Melos in CI/CD is similar to setting it up for your local machine.

1. Run `dart pub global activate melos`
2. Run `melos bootstrap`

Let’s check out the basic configuration in the `codemagic.yaml` file:

```yaml
workflows:
  ci:
    name: CI
    instance_type: mac_mini
    # Setting the timeout for a build to 15 minutes.
    max_build_duration: 15
    environment:
      # Using the latest Flutter version.
      flutter: stable
    # This workflow should trigger when a new pull request opens or updates.
    triggering:
      events:
        - pull_request
    scripts:
      - name: Add Dart SDK to PATH
         script: |
           echo PATH="$PATH":"$FLUTTER_ROOT/.pub-cache/bin" >> $CM_ENV
           echo PATH="$PATH":"$FLUTTER_ROOT/bin" >> $CM_ENV
      
      - name: Melos Bootstrap
         script: |
           dart pub global activate melos
           melos bootstrap
```

If you take closer look at the script, you’ll notice these lines:

```sh
echo 'export PATH="$PATH":"$FLUTTER_ROOT/.pub-cache/bin"' >> $CM_ENV 
echo 'export PATH="$PATH":"$FLUTTER_ROOT/bin"' >> $CM_ENV 
```

We need to add the paths to the Dart SDK to PATH to be able to run `dart` commands. Otherwise, we will get an error, like `dart: command not found`.

#### Run Melos scripts
Let’s add our Melos scripts to the `codemagic.yaml` file. This is how `codemagic.yaml` looks now:

```yaml
workflows:
  ci:
    name: CI
    instance_type: mac_mini
    # Setting the timeout for a build to 15 minutes.
    max_build_duration: 15
    environment:
      # Using the latest Flutter version.
      flutter: stable
    # This workflow should trigger when a new pull request opens or updates.
    triggering:
      events:
        - pull_request
    scripts:
      - name: Add Dart SDK to PATH
         script: |
           echo PATH="$PATH":"$FLUTTER_ROOT/.pub-cache/bin" >> $CM_ENV
           echo PATH="$PATH":"$FLUTTER_ROOT/bin" >> $CM_ENV
      
      - name: Melos Bootstrap
         script: |
          dart pub global activate melos
          melos bootstrap

      - name: Run Analyze
         script: melos run analyze

      - name: Run Format
         script: melos run format

      - name: Run Tests
         script: melos run test
```

#### Get the results of failed Golden tests
With Golden tests, you can render a widget and compare it with a screenshot. To understand more about Golden tests, check out this blog article on [how to run Flutter Golden (Snapshot) tests with Codemagic CI/CD](https://blog.codemagic.io/flutter-golden-tests-with-codemagic-cicd/). If you have Golden tests in your Flutter repo, you may want to access the results of failed Golden tests. When you use a monorepo, you need to check every package for the results of failed Golden tests. To do this, you can just run this script:

```yaml
...
- name: Run Tests
  script: |
    melos run test
    
    # Upload results of failed Golden tests if test command failed.
    if [ $? -ne 0 ]; then
      # Finds all "failures" folders and copies them to the export
      # directory. Therefore, we are able to view the results of the
      # failed Golden tests.
      #
      # The command will use the exit code 0 (success) even when there are
      # no failures folders.
      find * -path '**/failures' -execdir bash -c "cp -r failures $FCI_EXPORT_DIR" \;
      
      # Because we caught the exit code of the test command, we need to
      # set manually again.
      exit 1
    fi
```

### Configure path conditions
At the moment, we run our CI for every pull request no matter what changed in this pull request, even when we just change the documentation files or files in our back end (assuming we also have our back end in our monorepo).

However, you are using up unnecessary Codemagic build minutes.

To use your build minutes more efficiently, you can set path conditions. With path conditions, you can define that the CI should only run when changes have been made for specific paths.

Just use the `when` keyword to configure the paths:

```yaml
...
environment:
  # Using the latest Flutter version.
  flutter: stable
when:
  changeset:
    includes:
      # Only run the CI when a file in one of the following directories
      # changed.
      - "apps/**"
      - "packages/**"
      - "codemagic.yaml"
    excludes:
      # Don't run the CI when only .md files have changed.
      - "**/*.md"
# This workflow should trigger when a new pull request opens or updates.
triggering:
...
```

You can also check out the Codemagic documentation on [running builds and builds steps conditionally](https://docs.codemagic.io/yaml/yaml-conditional-run/) for more information about conditional runs.

## Conclusion
Monorepos are great for larger codebases. However, as you may have noticed in this article, they require a bit more effort to manage. Nevertheless, you should now be able to manage your own Flutter monorepo with Melos and configure your CI/CD.

You can check out the full source of the repository [here](https://github.com/nilsreichardt/codemagic_monorepo_example).

If you have configuration problems with Codemagic, just ask for help in the [Codemagic Slack](https://slack.codemagic.io/).