Monorepo Toolkit

The monorepo toolkit is a collection of CLI scripts generated into your project at devtools/scripts/. These tools help you manage a large Flutter monorepo — from dependency analysis to build preparation to asset optimization.

All commands are run from your project root via melos:

bash

melos run <command>

TIP

The toolkit is generated into your project so it works in CI without requiring the Archipelago CLI at build time. You own the code and can customize it.

Detailed Guides

Each script has a dedicated guide with config formats, examples, and CI integration:

Core Scripts (Free):

Run App — Interactive flavor and device selection
Build Prepare — Debug/release dependency swapping
Environment Sync — .env management across flavors
Flavor Manager — Flavor configuration (dev/staging/production)
Dependency Graph — Visualization and enforcement
Dependency Manager — Centralized version management
Workspace Setup — Workspace initialization
App Scaffold — Add new apps to workspace
Asset Generator — Type-safe asset enums
UI Kit Manager — Component and theme management

Extension Scripts (Pro/Enterprise):

Affected Packages — Git-based change detection Enterprise
Test Coverage — Coverage pipeline with thresholds Pro
Size Guard — File size enforcement Pro
Asset Optimizer — SVG/PNG/JPEG optimization Pro

`affected`

Detect which packages changed since the last release and run targeted operations only on affected packages.

`affected list`

List packages affected by changes since the given ref.

bash

melos run affected:list

`affected analyze`

Run static analysis only on affected packages.

bash

melos run affected:analyze

`affected test`

Run tests only on affected packages.

bash

melos run affected:test

`affected run`

Run a custom melos script only on affected packages.

bash

melos run affected:run -- <script-name>

TIP

Use affected in CI to skip unchanged packages and reduce pipeline time. It compares against the merge base of your PR branch.

`build-prepare`

Swap debug dependencies with no-op implementations for production builds, or restore them for development.

`build-prepare debug`

Restore debug/development dependencies.

bash

melos run build-prepare:debug

`build-prepare release`

Swap to release (no-op) dependencies for production builds.

bash

melos run build-prepare:release

How it works

Reads build_prepare.yaml at the workspace root and modifies pubspec.yaml files to swap dependency paths. Both debug and noop packages implement the same API contract, so the app compiles with either.

yaml

# build_prepare.yaml
swaps:
  - package: apps/your_app
    debug_dep: monitoring_impl
    release_dep: monitoring_noop
    dep_path: infrastructure/monitoring

WARNING

Always run build-prepare:debug after a release build to restore development dependencies. The Fastlane integration handles this automatically.

`coverage`

Manage test coverage across the monorepo.

`coverage init`

Initialize coverage configuration for all packages.

bash

melos run coverage:init

`coverage run`

Run tests with coverage collection.

bash

melos run coverage:run

`coverage combine`

Combine coverage reports from all packages into a single report.

bash

melos run coverage:combine

`coverage check`

Check that coverage meets the minimum threshold.

bash

melos run coverage:check

Key flags:

Flag	Description
`--min-coverage`	Minimum coverage percentage (default: 80)

`coverage full`

Run the full coverage pipeline: test, combine, and check.

bash

melos run coverage:full

TIP

Use coverage full in CI as a single command that runs tests, combines reports, and fails the build if coverage drops below the threshold.

`deps`

Manage dependencies across the monorepo.

`deps add`

Add a dependency to one or more packages.

bash

melos run deps:add -- <package-name> --target <target-package>

`deps remove`

Remove a dependency from one or more packages.

bash

melos run deps:remove -- <package-name> --target <target-package>

`deps internal`

List all internal (workspace) dependencies for a package.

bash

melos run deps:internal -- <package-name>

`deps external`

List all external (pub.dev) dependencies for a package.

bash

melos run deps:external -- <package-name>

`env`

Manage environment variables and flavor configurations.

`env init`

Initialize environment configuration for the project.

bash

melos run env:init

`env add`

Add a new environment variable.

bash

melos run env:add

`env sync`

Sync the flavor enum with the current flavors.yaml configuration.

bash

melos run env:sync

Flavor workflow

Define flavors in flavors.yaml at the workspace root
Run env:sync to generate the Dart enum
Each flavor has its own .env file (e.g., .env.dev, .env.staging, .env.prod)
Environment variables are code-generated with envied in the app_config package

`flavor`

Manage app flavors (variants like dev, staging, production).

`flavor list-apps`

List all apps in the workspace that support flavors.

bash

melos run flavor:list-apps

`flavor list`

List all defined flavors.

bash

melos run flavor:list

`flavor add`

Add a new flavor to the project.

bash

melos run flavor:add

`flavor generate`

Generate flavor-specific configuration files.

bash

melos run flavor:generate

`flavor sync`

Sync flavor definitions across all apps.

bash

melos run flavor:sync

`graph`

Analyze and visualize the dependency graph of the monorepo.

`graph visualize`

Generate a visual dependency graph.

bash

melos run graph:visualize

`graph stats`

Show dependency statistics (counts, depth, fan-in/fan-out).

bash

melos run graph:stats

`graph cycles`

Detect circular dependencies in the workspace.

bash

melos run graph:cycles

WARNING

Circular dependencies break the layered architecture. Run graph:cycles in CI to prevent them from being introduced.

`graph validate`

Validate the dependency graph against architecture rules (layer violations, forbidden dependencies).

bash

melos run graph:validate

`size-guard`

Monitor and enforce app binary size budgets.

`size-guard check`

Check the app binary size against defined budgets.

bash

melos run size-guard:check

TIP

Configure size budgets in your project config. The guard fails the build if the binary exceeds the limit, catching size regressions early.

`assets`

Manage and optimize image and media assets.

`assets optimize`

Optimize all image assets (compress PNGs, JPEGs, etc.).

bash

melos run assets:optimize

`asset-gen`

Generate Dart constants for assets.

`asset-gen generate`

Generate type-safe asset references from files in the assets directory.

bash

melos run asset-gen:generate

Example output

dart

// Generated — do not modify
class AppAssets {
  static const String logo = 'assets/images/logo.png';
  static const String onboarding1 = 'assets/images/onboarding_1.svg';
}

`ui-kit`

Manage UI kit components in the design system package.

`ui-kit list`

List all registered UI kit components.

bash

melos run ui-kit:list

`ui-kit add`

Add a new component to the UI kit.

bash

melos run ui-kit:add

`ui-kit remove`

Remove a component from the UI kit.

bash

melos run ui-kit:remove

`ui-kit status`

Show the status of all UI kit components (documented, tested, etc.).

bash

melos run ui-kit:status

`ui-kit create`

Scaffold a new UI kit package from scratch.

bash

melos run ui-kit:create

`theme-variant`

Manage theme variants (light, dark, high-contrast, brand-specific themes).

bash

melos run theme-variant

`workspace`

Workspace-level setup and configuration.

`workspace setup`

Run initial workspace setup (install dependencies, generate code, verify configuration).

bash

melos run workspace:setup

TIP

Run this after cloning the repo or when onboarding a new team member. It handles dart pub get, code generation, and environment setup in one command.

`app`

Manage app targets in the monorepo.

`app create`

Scaffold a new app target in the apps/ directory.

bash

melos run app:create

`config`

Manage project-wide configuration.

`config list`

List all configuration values.

bash

melos run config:list

`config publish`

Publish configuration to the workspace (syncs settings across packages).

bash

melos run config:publish

Quick Reference

Command	Description
`affected:list`	List changed packages
`affected:test`	Test changed packages only
`build-prepare:release`	Swap to release deps
`build-prepare:debug`	Restore debug deps
`coverage:full`	Full coverage pipeline
`graph:cycles`	Detect circular deps
`graph:validate`	Validate architecture rules
`workspace:setup`	Initial workspace setup
`env:sync`	Sync flavors
`assets:optimize`	Optimize images
`asset-gen:generate`	Generate asset constants

Monorepo Toolkit ​

Detailed Guides ​

affected ​

affected list ​

affected analyze ​

affected test ​

affected run ​

build-prepare ​

build-prepare debug ​

build-prepare release ​

coverage ​

coverage init ​

coverage run ​

coverage combine ​

coverage check ​

coverage full ​

deps ​

deps add ​

deps remove ​

deps internal ​

deps external ​

env ​

env init ​

env add ​

env sync ​

flavor ​

flavor list-apps ​

flavor list ​

flavor add ​

flavor generate ​

flavor sync ​

graph ​

graph visualize ​

graph stats ​

graph cycles ​

graph validate ​

size-guard ​

size-guard check ​

assets ​

assets optimize ​

asset-gen ​

asset-gen generate ​

ui-kit ​

ui-kit list ​

ui-kit add ​

ui-kit remove ​

ui-kit status ​

ui-kit create ​

theme-variant ​

workspace ​

workspace setup ​

app ​

app create ​

config ​

config list ​

config publish ​

Quick Reference ​

Monorepo Toolkit

Detailed Guides

`affected`

`affected list`

`affected analyze`

`affected test`

`affected run`

`build-prepare`

`build-prepare debug`

`build-prepare release`

`coverage`

`coverage init`

`coverage run`

`coverage combine`

`coverage check`

`coverage full`

`deps`

`deps add`

`deps remove`

`deps internal`

`deps external`

`env`

`env init`

`env add`

`env sync`

`flavor`

`flavor list-apps`

`flavor list`

`flavor add`

`flavor generate`

`flavor sync`

`graph`

`graph visualize`

`graph stats`

`graph cycles`

`graph validate`

`size-guard`

`size-guard check`

`assets`

`assets optimize`

`asset-gen`

`asset-gen generate`

`ui-kit`

`ui-kit list`

`ui-kit add`

`ui-kit remove`

`ui-kit status`

`ui-kit create`

`theme-variant`

`workspace`

`workspace setup`

`app`

`app create`

`config`

`config list`

`config publish`

Quick Reference