Staged Runner

CLI to run build_runner only on modified .dart files.

Problem

In large Flutter/Dart projects, build_runner can take a long time because it generates code for all files. During development, when you only modify one or a few files, this is inefficient.

Solution

This CLI detects modified .dart files (staged + unstaged) and temporarily modifies build.yaml to run build_runner only on those files.

Installation

npm install -g staged-runner

Usage

cd my-flutter-project

# Just run it - it detects modified files automatically
sr

# Scan dependencies (recommended for smart rebuilds)
sr deps

# Force full dependency scan
sr deps --force

Configuration

Create a .staged-runner/config.json file in your project root:

{
  "paths": ["lib", "packages/core/lib"],
  "dependency_patterns": ["^\\s*enum\\s+\\w+\\s*\\{"]
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | paths | string[] | ["lib"] | Paths to scan for dependencies | | dependency_patterns | string[] | null | Regex patterns to filter which files generate reverse dependencies |

Dependency Patterns

The dependency_patterns option allows you to control which files generate reverse dependencies. This is useful when you only want to rebuild dependents for specific types of files (like enums).

Example: When using json_serializable, enums are regenerated in every model that uses them. To ensure models are rebuilt when an enum changes:

dependency_patterns:
  - "^\\s*enum\\s+\\w+\\s*\\{"

| Pattern Part | Meaning | |--------------|---------| | ^ | Start of line | | \\s* | Zero or more whitespace | | enum | The enum keyword | | \\s+ | One or more whitespace | | \\w+ | Enum name | | \\s* | Zero or more whitespace | | \\{ | Opening brace |

This pattern matches enum declarations like:

enum UserStatus {      // ✓ matches
  active,
  inactive,
}

But does NOT match:

import 'user_status_enum.dart';  // ✗ not a declaration
// enum commented                  // ✗ comment

What happens

1. Detects modified .dart files (staged + unstaged)
2. Expands with reverse dependencies (if sr deps was run)
3. Backs up build.yaml to build.yaml.lock
4. Modifies build.yaml adding generate_for with files to build
5. Runs fvm dart run build_runner build --delete-conflicting-outputs
6. Protects modified files and their generated counterparts
7. Reverts unintended deletions
8. Restores build.yaml from backup

Commands

| Command | Description | |---------|-------------| | sr | Run build_runner on modified files | | sr deps | Scan and cache file dependencies | | sr deps --force | Force full rescan ignoring cache |

Requirements

• Node.js >= 18
• FVM
• Git
• Dart/Flutter project with pubspec.yaml and build.yaml

License

MIT