// Upgrade flutter_rust_bridge to a new Flutter stable release. Use when changing Flutter/Dart versions, devcontainer Docker images, CI/post-release pins, generated Flutter scaffolds, or platform compatibility.
Use when the user wants Docker-based FRB development or Tart-based iOS Simulator validation.
Use when preparing or explaining the FRB Tart base VM for iOS Simulator validation, including local OCI registry mirroring, direct OCI clone, and base VM hygiene.
Explain how cargokit is sourced, copied, and analyzed inside flutter_rust_bridge. Use when working on `integration_template/**/cargokit`, `frb_example/**/cargokit`, integrate/generate output drift, or any diff that mentions cargokit and you need to identify the true source of truth before judging the change.
Use when about to create a PR or push changes in flutter_rust_bridge to ensure code generation is up to date
Use when implementing a GitHub issue, bug fix, or feature in flutter_rust_bridge end-to-end: develop the change, add regression coverage, prepare and open a PR, monitor CI until green, request and resolve Gemini review, and keep following up on a 5 minute cadence until the PR is ready.
Review a flutter_rust_bridge PR before treating it as ready, including subagent checks for correctness and test weakening plus Gemini review.
| name | frb-upgrade-flutter |
| description | Upgrade flutter_rust_bridge to a new Flutter stable release. Use when changing Flutter/Dart versions, devcontainer Docker images, CI/post-release pins, generated Flutter scaffolds, or platform compatibility. |
Use this as the single-file workflow for Flutter stable bumps in flutter_rust_bridge.
frb-docker before changing .devcontainer/** or publishing the dev image.frb-code-generation before accepting generated or scaffold drift.frb-cargokit or frb-cargokit-dev before changing copied cargokit files.frb-pr-review before treating the upgrade PR as ready.frb-fix-ci when CI starts failing..github/workflows/ci.yaml and .github/workflows/post_release.yaml toolchain env values in sync..devcontainer/Dockerfile ARG values as the source of truth for dev image tags..devcontainer/Dockerfile, build a fresh local image from that Dockerfile and use a
container based on that fresh image for local validation. Do not keep using an older per-worktree
container whose Flutter, Dart, Rust, Android, or browser tooling may still be stale.master.Use official Flutter sources. Record the target Flutter version, bundled Dart version, release date, and release-note items likely to affect FRB.
Scan for:
Plan one PR for the Flutter upgrade. Keep the PR internally organized by logical commits or phases, but do not split the upgrade across multiple PRs unless Tom explicitly asks.
Use this order inside the single PR:
Run these before planning the bump:
rg -n \
"FRB_MAIN_|FLUTTER_VERSION|DART_VERSION|RUST_VERSION|setup-flutter|setup-dart|cirruslabs/flutter"
rg -n "flutter_rust_bridge_dev|3\\.[0-9]+"
Inspect at least:
.devcontainer/Dockerfile.github/workflows/ci.yaml.github/workflows/post_release.yaml.github/workflows/publish_dev_docker.yamltools/frb_internal/test/src/makefile_dart/test_dev_docker_metadata.dartpubspec.yaml, package pubspec.yaml files, and checked-in pubspec.lock filesfrb_codegen/assets/integration_template/**tools/frb_internal/assets/apple_scaffold/**frb_example/**Update .devcontainer/Dockerfile:
ARG FLUTTER_VERSIONUpdate metadata tests that assert the derived dev image tag.
Build and smoke-test locally when practical. If an old per-worktree container already exists, do not use it for this step; create a fresh container from the newly built image, or rebuild/recreate the per-worktree container so it uses the updated Dockerfile contents.
docker build -f .devcontainer/Dockerfile -t frb-dev .devcontainer
docker run --rm -v "$PWD:/workspace" -w /workspace frb-dev bash -lc './frb_internal --help'
docker run --rm -v "$PWD:/workspace" -w /workspace frb-dev bash -lc '
set -euo pipefail
flutter --version
dart --version
node --version
npm --version
cargo --version
wasm-pack --version
"${CHROME_BIN}" --version
'
If local build is too expensive, dry-run the workflow:
gh workflow run publish_dev_docker.yaml --ref <branch> -f publish=false
Update top-level env values together in .github/workflows/ci.yaml and
.github/workflows/post_release.yaml:
FRB_MAIN_FLUTTER_VERSIONFRB_MAIN_DART_VERSIONFRB_MAIN_RUST_VERSION if the Flutter or tooling bump requires newer RustFRB_RUSTFMT_NIGHTLY_VERSION only if formatting or nightly-only rust-src behavior requires itpost_release.yaml intentionally says it should stay in sync with ci.yaml. It verifies released
quickstart and codegen installation modes, so do not leave it pinned to old Flutter/Dart versions.
Scan workflow assumptions:
flutter-actions/setup-flutterdart-lang/setup-dartcodegen_install_mode coverage for cargo-install, cargo-binstall, scoop, and
homebrewRead frb-code-generation first.
Expect drift in:
pubspec.lock Dart SDK constraintsflutter create / flutter integrate scaffold outputfrb_generated.* files if Dart formatting, analyzer behavior, or codegen dependencies changedClassify by source:
frb_codegen/assets/integration_template/**.tools/frb_internal/assets/apple_scaffold/**../frb_internal generate-* or precommit-* command.Run focused generation first when possible, then broaden:
./frb_internal precommit-generate
./frb_internal precommit-integrate
If multiple generated-output CI failures rotate across packages, stop package-by-package fixes and run
a clean full ./frb_internal precommit-generate.
Read frb-lint and frb-test for exact command guidance. Tom's FRB environment runs tests locally,
usually through the per-worktree Docker container.
If the Flutter upgrade changed .devcontainer/Dockerfile, first ensure local validation is running
inside the fresh image built in Step 4. Seeing an old Dart or Flutter version locally means the
container is stale; recreate it before trusting any validation result.
Recommended minimum validation:
./frb_internal lint --fix
./frb_internal test-dart-native --package frb_example/pure_dart
./frb_internal test-dart-native --package frb_example/pure_dart_pde
./frb_internal test-flutter-native --package frb_example/flutter_via_create
./frb_internal test-flutter-web --package frb_example/gallery
For CI or Docker plumbing-only changes, dev image dry-run and focused metadata tests may be enough before opening the PR. Let CI cover the full matrix.
Before treating the upgrade PR as ready, run the review gate in frb-pr-review.
Read frb-fix-ci before deep debugging.
When a platform starts failing after the Flutter bump, compare against release notes before patching symptoms. Flutter stable bumps often intentionally change generated platform projects.
After the single upgrade PR is merged into master, trigger the publish workflow from master so the
new derived dev image tag exists for future CI and developer workflows:
gh workflow run publish_dev_docker.yaml --ref master
After it completes, verify both linux/amd64 and linux/arm64:
docker buildx imagetools inspect fzyzcjy/flutter_rust_bridge_dev:latest
docker buildx imagetools inspect fzyzcjy/flutter_rust_bridge_dev:flutter-<flutter>-rust-<rust>-nightly-<nightly>
BuildKit attestation manifests can appear as unknown/unknown; those are not platform images.
For the single upgrade PR, include: