How to flag new dependencies in Flutter pull requests

Docs/Tutorials/detect_new_library

Pro Reference for detect_new_library: every variable, option and package it generates. Command: archipelago generate detect_new_library

Add the detect-new-library command, see how it finds new direct dependencies, run it locally and in CI, and make it a blocking gate.

What you'll learn

• Adding the detect-new-library command to your monorepo toolkit
• Seeing how it finds newly added direct dependencies
• Running it locally and in CI
• Switching from report-only to a blocking gate

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Monorepo Toolkit already generated (see Monorepo Toolkit Setup)
• A Pro or Enterprise subscription

Step 1: Generate the Tool

New Pro projects already include this brick. Run it on an older project:

archipelago generate detect_new_library

The prompts are:

• appName: the name of your app
• isForMonorepo: leave this as true

Or use a config file:

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

archipelago generate detect_new_library --config detect_new_library_config.json

Step 2: Understand the Generated Structure

devtools/scripts/detect_new_library/
└── lib/src/
    ├── commands/        # detect-new-library and its check subcommand
    ├── models/new_library_config.dart
    └── services/detect_new_library_service.dart

.newlibrary.yaml         # Workspace root config

The hook registers DetectNewLibraryCommand in the toolkit. It creates .newlibrary.yaml with fail_on_new: false, so the first run only reports. Commit both.

Step 3: Know What It Detects

The tool finds every pubspec.yaml that changed against the base branch. It compares the dependencies sections and reports each package added directly. Transitive dependencies are not reported.

The tool picks the base branch from the CI environment. Pass --base to choose one.

Step 4: Run the Check Locally

dart run monorepo_toolkit detect-new-library check
dart run monorepo_toolkit detect-new-library check --base develop

By default the command prints a report and exits 0 even when it finds new libraries.

Step 5: Configure the Policy

Edit .newlibrary.yaml at the workspace root:

fail_on_new: false

ignored_packages:
  - flutter
  - dart

Set fail_on_new: true to exit with code 1 on any new library. Or pass --fail for one run. ignored_packages matches exact package names only. base_branch is an optional key that fixes the comparison branch.

Step 6: Add It to CI

- name: Detect new libraries
  run: dart run monorepo_toolkit detect-new-library check --base origin/${{ github.base_ref }}

Without --fail or fail_on_new: true, this step never blocks a PR. That is the default on purpose. It makes new dependencies visible in review.

To block a PR, add --fail. The author then removes the package or gets team approval and adds the package name to ignored_packages.

Common Customizations

Customization	Where to Change
Allow known-safe packages	ignored_packages in .newlibrary.yaml
Change the comparison branch	--base or base_branch
Make the check blocking	fail_on_new: true or --fail

Next Steps

• Add the Size Analyzer to catch binary size regressions alongside new dependency alerts
• Configure CI/CD to run both checks on every PR