Setting Up the Monorepo Toolkit

What you'll learn

• Generating the devtools/ CLI toolkit for your monorepo
• Available commands for dependency management and code generation
• Running affected-only builds in CI
• Extending the toolkit with custom scripts

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

Step 1: Generate the Monorepo Toolkit

archipelago generate monorepo_toolkit

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• organization — MyCompany (your organization name)
• isForMonorepo — true

Or use a config file:

{
  "appName": "MyApp",
  "organization": "MyCompany",
  "isForMonorepo": true
}

archipelago generate monorepo_toolkit --config toolkit_config.json

Step 2: Understand the Generated Structure

devtools/
├── monorepo_toolkit/
│   ├── bin/
│   │   └── monorepo_toolkit.dart    # CLI entry point
│   ├── lib/src/
│   │   ├── commands/                # All CLI commands
│   │   ├── utils/                   # Shared utilities
│   │   └── monorepo_toolkit.dart    # Command runner
│   └── pubspec.yaml
└── scripts/
    ├── affected/                    # Detect changed packages
    ├── coverage/                    # Aggregate coverage reports
    ├── build_prepare/               # Flavor-based dependency swapping
    └── dependency_graph/            # Visualize package dependencies

Step 3: Activate the Toolkit

cd devtools/monorepo_toolkit
dart pub get
dart run bin/monorepo_toolkit.dart --help

Or activate globally for convenience:

dart pub global activate --source path devtools/monorepo_toolkit
monorepo_toolkit --help

Step 4: Key Commands

Command	Purpose
affected	List packages changed since a git ref
coverage	Aggregate test coverage across packages
build-prepare	Swap impl/noop dependencies per flavor
dep-graph	Generate a dependency graph visualization

Example: run tests only on affected packages in CI:

monorepo_toolkit affected --since origin/main | xargs -I {} sh -c 'cd {} && flutter test'

Step 5: CI Integration

Add the toolkit to your GitHub Actions workflow:

- name: Get affected packages
  run: |
    dart pub global activate --source path devtools/monorepo_toolkit
    AFFECTED=$(monorepo_toolkit affected --since ${{ github.event.pull_request.base.sha }})
    echo "affected=$AFFECTED" >> $GITHUB_OUTPUT

Common Customizations

Customization	How
Add a new command	Create a Command class in commands/
Change affected detection	Modify scripts/affected/ logic
Custom coverage thresholds	Edit scripts/coverage/ configuration
Add pre-build hooks	Extend build_prepare script

Next Steps

• Set up Size Guard to enforce file size limits
• Add UI Kit Generator commands to the toolkit