flutter_restore logo

flutter_restore

Static compatibility scanner for restoring and auditing old Flutter projects.

flutter_restore reads project files, builds a structured snapshot, runs compatibility rules, and prints a plain text or JSON report. It does not run Flutter, Gradle, Xcode, CMake, package resolution, or any build step.

Overview #

Old Flutter projects often fail before application code is reached. The usual failure points are stale runner files, obsolete Gradle or CMake setup, old web bootstrap templates, deprecated platform integration, and native build settings that modern tooling no longer expects.

flutter_restore helps answer:

What is old, risky, or incompatible here before I try to run it?

The scanner is designed for:

restoring abandoned Flutter applications
auditing projects before migration
estimating native migration effort
producing machine-readable compatibility reports
inspecting fragile repositories without executing old build scripts

Installation #

From this repository:

dart pub get

Run directly:

dart run flutter_restore scan path/to/flutter/project

Activate locally during development:

dart pub global activate --source path .
flutter_restore scan path/to/flutter/project

Usage #

Run a plain text scan:

dart run flutter_restore scan path/to/project

Run a JSON scan:

dart run flutter_restore scan --json path/to/project

Scan every supported platform:

dart run flutter_restore scan --platform all path/to/project

Scan a single platform:

dart run flutter_restore scan --platform android path/to/project
dart run flutter_restore scan --platform ios path/to/project
dart run flutter_restore scan --platform linux path/to/project
dart run flutter_restore scan --platform windows path/to/project
dart run flutter_restore scan --platform web path/to/project

Print an ordered migration plan instead of a raw findings report:

dart run flutter_restore plan path/to/project
dart run flutter_restore plan --json path/to/project

The plan command accepts the same --json and --platform options as scan.

Supported Platforms #

Platform	Static Facts	Compatibility Rules
Android	Gradle, AGP, Kotlin, SDK levels, Flutter Gradle integration, embedding	Java/Gradle, AGP/Gradle, AGP/Java, AGP/SDK, legacy Flutter Android migration
iOS	deployment targets, Podfile, SwiftPM, CocoaPods, AppDelegate, Xcode project settings	deployment target, dependency management, lifecycle, AppDelegate, Xcode project consistency
Linux	runner files, CMake baseline, GTK pkg-config wiring	target presence, runner completeness, CMake minimum, GTK pkg-config
Windows	runner files, CMake baseline, run loop, version metadata, title bar, first-frame redraw	target presence, runner completeness, CMake minimum, run loop, version info, dark title bar, ForceRedraw
Web	index template, manifest, favicon, bootstrap, service worker wiring, base href	target presence, runner completeness, bootstrap, loader API, service worker, base href
Dependencies	pubspec.yaml constraints, pubspec.lock resolved versions, SDK pins	lock consistency, Dart/Flutter SDK requirements, known package conflicts, deprecated packages

Rules #

Rules emit Finding objects with stable ids, severity, location, detected value, and recommendation fields when useful.

Project-wide rules:

missing-pubspec
missing-pubspec-lock
missing-metadata

Android rules:

gradle-java-17-unsupported
missing-gradle-version
missing-agp-version
unknown-agp-gradle-range
agp-gradle-mismatch
agp-java-requirement
agp-compile-sdk-too-new
legacy-flutter-gradle-apply
flutter-plugins-file
android-v1-embedding
missing-plugin-dsl

iOS rules:

ios-deployment-target-too-low
ios-podfile-platform-too-low
ios-deployment-target-mismatch
ios-plugin-deployment-target-conflict
ios-plugin-deployment-target-too-low
ios-swiftpm-disabled
ios-legacy-cocoapods-only
ios-mixed-dependency-management
ios-legacy-flutter-podfile-integration
ios-potential-cocoapods-only-plugins
ios-uiscene-incomplete
ios-custom-appdelegate-only-lifecycle
ios-manual-generated-plugin-registrant
ios-custom-platform-integration-in-appdelegate
ios-implicit-engine-lifecycle
ios-legacy-flutter-engine-initialization
ios-suspicious-flutter-xcconfig
ios-old-flutter-build-script
ios-legacy-framework-embedding
ios-legacy-build-setting

Linux rules:

linux-platform-directory-missing
linux-runner-files-incomplete
linux-cmake-minimum-too-low
linux-gtk-pkg-config-missing

Windows rules:

windows-platform-directory-missing
windows-runner-files-incomplete
windows-cmake-minimum-too-low
windows-legacy-run-loop
windows-version-info-not-tool-driven
windows-dark-title-bar-support-missing
windows-force-redraw-missing

Web rules:

web-platform-directory-missing
web-runner-files-incomplete
web-bootstrap-missing
web-base-href-missing
web-legacy-load-entrypoint
web-custom-bootstrap-incomplete
web-deprecated-service-worker-version
web-manual-service-worker-registration

Desktop rules:

desktop-legacy-target-platform-override

Dependency rules (project-wide, driven by pubspec.yaml and pubspec.lock):

dependency-missing-from-lock
dependency-constraint-lock-mismatch
dependency-stale-lock-entry
dependencies-require-newer-dart-sdk
dependencies-require-newer-flutter-sdk
dependencies-declared-dart-range-too-wide
dependencies-declared-flutter-range-too-wide
package-requires-newer-dart-sdk
incompatible-packages-<first>-<second>
package-note-<name>

The built-in package tables cover common packages and known conflicts (for example intl vs. flutter_localizations, or dart_code_metrics vs. analyzer 6). They are heuristics, not a resolver: extend CompatibilityData with your own entries when auditing a codebase with internal packages.

Reports #

Plain text output is intended for humans and uses colored severity labels.

flutter_restore scan
Project: /projects/legacy_app
Package: legacy_app

Android
  Gradle: 5.6.4
  AGP: 3.5.4
  Kotlin: 1.3.50
  SDK: compile=35, min=21, target=28
  Legacy flutter.gradle apply: true
  .flutter-plugins: true
  Android v1 embedding: true
  Plugin DSL: false

Findings
  [HIGH] Gradle 5.6.4 is too old for Java 17
    This Gradle line supports Java up to 16; modern Android builds commonly use Java 17.
    android/gradle/wrapper/gradle-wrapper.properties

JSON output is intended for scripts, CI, dashboards, and later automation.

{
  "platforms": ["android"],
  "snapshot": {
    "rootPath": "/projects/legacy_app",
    "hasPubspec": true,
    "hasPubspecLock": true,
    "hasMetadata": true,
    "pubspecName": "legacy_app",
    "flutterRevision": "0123456789abcdef",
    "android": {
      "gradleVersion": "5.6.4",
      "agpVersion": "3.5.4",
      "kotlinVersion": "1.3.50",
      "compileSdk": 35,
      "minSdk": 21,
      "targetSdk": 28,
      "usesLegacyFlutterGradleApply": true,
      "hasFlutterPluginsFile": true,
      "usesAndroidV1Embedding": true,
      "usesPluginDsl": false
    }
  },
  "findings": [
    {
      "id": "legacy-flutter-gradle-apply",
      "severity": "HIGH",
      "title": "Legacy Flutter Gradle apply detected",
      "message": "The Android project applies flutter.gradle with apply from, which is incompatible with newer Flutter Gradle integration.",
      "location": "android/app/build.gradle"
    }
  ]
}

Severity levels:

BLOCKER: analysis cannot continue as expected, or migration is blocked
HIGH: likely build or migration failure
MEDIUM: important migration risk or missing precision
INFO: useful context for restoration planning

Migration Plans #

flutter_restore plan turns scan findings into an ordered, advisory migration plan. It is deliberately not an autofix: old Flutter projects often contain custom changes in android/ and ios/, and blindly regenerating platform files can destroy that customization. The plan describes what to migrate, why, which files are affected, and which steps must happen first.

Migration plan

[1] Upgrade Android Gradle infrastructure
    reason: AGP/Gradle incompatible with current Java
    affects:
      android/build.gradle
      android/gradle/wrapper/gradle-wrapper.properties

[2] Migrate Flutter Gradle plugin application
    depends_on: 1

[3] Migrate Android embedding
    depends_on: 2

Estimated risk: HIGH
Native customization detected: YES

Step numbering is one-based and stable, so depends_on always refers to earlier steps. Estimated risk is derived from the most severe finding (LOW, MEDIUM, or HIGH), and Native customization detected reports whether custom native code was found in platform runners. The plan command always exits with code 0; use scan when exit codes matter.

Exit Codes #

Code	Meaning
`0`	scan completed without blocker findings
`2`	scan completed and at least one blocker finding was reported
`64`	command line usage error

Architecture #

The project is split into small layers:

scanners read files and collect facts
models represent discovered project state
compatibility data lives separately from rule logic
rules analyze a ProjectSnapshot
the plan builder turns findings into an ordered MigrationPlan
renderers format output
the CLI wires the flow together

scan -> ProjectSnapshot -> CompatibilityRule -> Finding -> report
                                             \-> MigrationPlanBuilder -> MigrationPlan -> plan report

The rule runner is split with Dart part files:

rule_runner.project.dart
rule_runner.android.dart
rule_runner.ios.dart
rule_runner.platforms.dart

Development #

Install dependencies:

dart pub get

Run tests:

dart test

Run static analysis:

dart analyze

Format code:

dart format .

The test suite includes scanner tests, rule tests, CLI integration tests, and fixtures for legacy and modern Flutter project layouts.

Maintainers #

Vortex-bit256

flutter_restore 1.3.0
flutter_restore: ^1.3.0 copied to clipboard

Metadata

flutter_restore

Table of Contents #

Overview #

Installation #

Usage #

Supported Platforms #

Rules #

Reports #

Migration Plans #

Exit Codes #

Architecture #

Development #

Maintainers #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

Dependencies

More

flutter_restore 1.3.0 flutter_restore: ^1.3.0 copied to clipboard

Metadata

flutter_restore

Table of Contents #

Overview #

Installation #

Usage #

Supported Platforms #

Rules #

Reports #

Migration Plans #

Exit Codes #

Architecture #

Development #

Maintainers #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

Dependencies

More

flutter_restore 1.3.0
flutter_restore: ^1.3.0 copied to clipboard