Getting Started

Getting started

SPM requires Dart 3.9.2 or newer and Flutter 3.3 or newer.

Install the CLI

Install SPM globally from pub.dev:

dart pub global activate spm

If you prefer a project-local command, add it as a development dependency:

flutter pub add dev:spm
dart run spm:spm analyze --output results.jsonl /path/to/flutter/project

Run dart pub get from the repository root when working on SPM itself.

Analyze and profile a project

Start by creating one static-analysis row for every rebuild scope:

spm analyze --output results.jsonl /path/to/flutter/project

To analyze only State subclasses, narrow the scope types:

spm analyze --output results.jsonl --scope-types State /path/to/flutter/project

The simplest profiling path lets run inject the SpmState base class, launch Flutter in profile mode, and restore the source afterward:

spm run --jsonl results.jsonl --flutter run

You can perform the transformation separately when you need to control the Flutter command:

spm inject --jsonl results.jsonl /path/to/flutter/project
# Launch the instrumented app here.
spm inject --jsonl results.jsonl --mode remove /path/to/flutter/project

Always remove a standalone injection when the profiling run is finished.

Use the standalone commands

isolate extracts rebuild scopes into smaller Dart files:

spm isolate --output-dir ./isolated_widgets /path/to/flutter/project

validate checks that a mutation changes widget-tree structure without changing frozen content or state:

spm validate --base base.dart --mutation mutation.dart

Continue with the individual command pages for flags and failure behavior. Output Formats describes the records produced by analyze and run.