How to set up the monorepo toolkit for a Flutter workspace

Docs/Tutorials/monorepo_toolkit

Free Reference for monorepo_toolkit: every variable, option and package it generates. Command: archipelago generate monorepo_toolkit

Generate the devtools toolkit, run its core commands, see how extension bricks add commands, and use it in CI.

What you'll learn

• Generating the devtools/ toolkit for your monorepo
• Running the core commands
• Seeing how extension bricks add commands
• Using the toolkit in CI

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

New projects already include the toolkit. It is generated into your project, so CI needs no Archipelago CLI.

Step 1: Generate the Monorepo Toolkit

archipelago generate monorepo_toolkit

The prompts are:

• appName: your app name, for example MyApp
• organization: your company name
• isForMonorepo: leave this as 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/command_runner.dart   # Registers every command
└── scripts/
    ├── app_scaffold/                 # app
    ├── build_prepare/                # build-prepare
    ├── dependency_graph/             # graph
    ├── dependency_manager/           # deps
    ├── env_sync/                     # env
    ├── flavor_manager/               # flavor
    ├── host_registry_generator/      # generate
    ├── prepare/                      # prepare
    ├── run_app/                      # run
    ├── shared_scripts/               # Shared library, not a command
    └── workspace_setup/              # workspace

Step 3: Run the Toolkit

Run commands from the project root:

dart run monorepo_toolkit --help
dart run monorepo_toolkit graph validate

Most commands also have a melos shortcut, for example melos run graph:cycles. Pass --verbose for more output and --version to print the toolkit version.

Step 4: Know the Core Commands

Command	Purpose
app create	Add a new app to the workspace
build-prepare	Swap debug tooling for noop packages per flavor
deps	Add, remove and list shared dependencies
env	Manage .env files per flavor
flavor	Add and sync flavors
graph	Visualize and validate the package graph
generate host-registry	Rebuild the DI marker regions in injector.dart
generate test-harness	Rebuild the composition-root test harness
run	Pick a flavor and device, then run the app
workspace	Set up and validate the workspace

Some examples:

dart run monorepo_toolkit env switch --flavor development --if-missing
dart run monorepo_toolkit build-prepare --flavor production
dart run monorepo_toolkit generate host-registry --check

generate host-registry --check exits 1 when injector.dart is out of date. The generated melos run di:check runs both generators with --check.

Step 5: Extension Commands

Other bricks add commands to command_runner.dart from their own hooks:

Brick	Tier	Command
asset_generator	Free	asset-gen
ui_kit_generator	Free	ui-kit, theme-variant
coverage_manager	Pro	coverage
size_guard	Pro	size-guard
asset_optimizer	Pro	assets
detect_new_library	Pro	detect-new-library
size_analyzer	Pro	size-analyzer
permission_guard	Pro	permission-guard
affected	Enterprise	affected

A melos shortcut for a script you did not generate fails until its brick is installed.

Step 6: CI Integration

Run the toolkit with dart run. Pro and Enterprise projects get pr-checks.yml and update-baselines.yml that call these scripts. Add your own steps the same way:

- name: Validate the dependency graph
  run: dart run monorepo_toolkit graph validate

- name: Check DI wiring
  run: dart run monorepo_toolkit generate host-registry --check

Common Customizations

Customization	How
Add a command	A Command class in a new script package, registered in command_runner.dart
Change a script	Edit its package under devtools/scripts/. You own the code
Add pre-build steps	Extend the build_prepare script

Next Steps

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