Setting Up the Detect New Library Tool

What you'll learn

• Generating the Detect New Library devtool and integrating it into the monorepo toolkit
• Understanding how the tool identifies newly added direct dependencies
• Blocking PRs that introduce unapproved libraries in CI
• Configuring the .newlibrary.yaml workspace config

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Monorepo Toolkit already generated (see Monorepo Toolkit Setup)

Pro Feature

detect_new_library is available on the Pro tier and above.

Step 1: Generate the Detect New Library Tool

archipelago generate detect_new_library

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• isForMonorepo — true (registers the command into the monorepo toolkit)

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/
│       ├── detect_new_library_command.dart  # Registered toolkit command
│       ├── parser.dart                      # Parses pubspec.yaml changes
│       └── reporter.dart                    # Formats output / exit codes
└── pubspec.yaml

.newlibrary.yaml                             # Workspace root config

The post_gen hook registers detect-new-library into your monorepo toolkit and creates .newlibrary.yaml at the workspace root with fail_on_new: false so the first run is report-only. Commit both files.

Step 3: Understand What Gets Detected

The tool diffs the dependencies: and dev_dependencies: sections of every pubspec.yaml that was modified in the current PR branch (compared against the target branch). It flags any package that appears in the changed file but not in the base branch — i.e., a newly added direct dependency.

Transitive dependencies are not flagged; only packages explicitly listed in a pubspec.yaml that the PR touched.

Step 4: Run the Check Locally

dart run devtools/monorepo_toolkit/bin/monorepo_toolkit.dart \
  detect-new-library check

With fail_on_new: false (the default), the command prints a report and exits 0 even when new libraries are found. Switch to fail_on_new: true when your team is ready to enforce the gate.

Example output when a new package is found:

[detect-new-library] New libraries detected in PR:

  packages/feature_payments/pubspec.yaml
    + stripe_flutter ^10.2.0

  1 new library requires approval before merging.

Step 5: Configure the Workspace Policy

Edit .newlibrary.yaml at the workspace root:

fail_on_new: true   # exits non-zero when any new library is detected

Set fail_on_new: true in CI to block merges. Keep it false locally if you want advisory-only output during development.

Step 6: CI Integration

Add the check to your PR workflow after dart pub get (so packages resolve):

- name: Detect new libraries
  run: |
    dart pub global activate --source path devtools/monorepo_toolkit
    monorepo_toolkit detect-new-library check

When fail_on_new: true, the step fails if any new direct dependency appears in PR-changed pubspec.yaml files. The PR author must either:

1. Remove the unapproved package, or
2. Get explicit team approval, then have a maintainer merge a separate commit that updates .newlibrary.yaml with an approved: list (if you extend the tool), or
3. Set fail_on_new: false temporarily and document the exception in the PR description.

Common Customizations

Customization	Where to Change
Allowlist known-safe packages	Extend DetectNewLibraryCommand with an allowed: list in .newlibrary.yaml
Ignore dev dependencies	Filter dev_dependencies: in parser.dart
Custom report format	Modify reporter.dart to output JSON for downstream tooling
Change comparison base	Pass --base <ref> to compare against a different git ref

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