Flutterware #

A desktop studio for your Flutter project, with the same tools for your coding agent.

Live previews, widget tests that picture every step, store screenshots, and your app on a device you can drive. All of it also runs from the terminal.

Open the web demo to look around before installing anything. It is the studio itself, compiled for the web and opened on the demo app, a small coffee shop: the previews run live in the page, and every other tool shows what it found on a recorded run of the app. Nothing in it can change.

Try it on your machine #

Clone the demo, the coffee shop app with every tool turned on, and start the studio:

git clone https://github.com/flutterware/flutterware_example
cd flutterware_example
dart run flutterware

The first launch builds the studio, so give it a minute.

You need Flutter 3.47 or newer. Live previews are macOS only for now; the rest also runs on Linux and Windows.

What's in it #

Previews	Scenarios
Your @Preview widgets on a device frame, in a live engine. Change the device, the language or the theme, turn knobs, read the widget tree.	Widget tests that keep a screenshot, the widget tree and the visible text of every step. The studio draws each run as a flow.
Store screenshots	Translations
App Store and Google Play images made from your tests, for every language, at the sizes each store asks for. The frame is a widget you write.	Every key in every language, next to a picture of where it appears. Missing and overlong strings are flagged.
Run	Comparison
Your app on a simulator, a phone or the desktop: its logs, network calls, widget tree and permissions, and every tap an agent made, step by step.	What a branch changed on screen. fw compare renders both sides from git and exports a page to link from the pull request.
Changes	Server
Your branch's diff with the files that matter listed first, and notes you can leave for your agent.	The requests your Dart backend handles, the SQL each one ran, and N+1 queries flagged.
Launcher icon	Splash screen
Every app icon, as each platform will show it, and what's wrong with them.	What each platform shows at launch, read from the generated files.

And the rest:

Each tool has a guide in doc/.

Scenarios are widget tests #

scenario('Around the shop', (s) async {
  await s.pumpWidget(const ShopApp());
  await s.tap(ShopKeys.getStarted);
  await s.split({
    'a cold brew': () async {
      await s.tap('Cold brew');
      await s.tap(ShopKeys.addToCart);
      await s.tap(ShopKeys.placeOrder);
    },
    'the empty cart': () async {
      await s.tap(ShopKeys.openCart);
    },
  });
});

flutter test runs this like any other test. Each step waits for the screen to settle, then keeps what it showed. s.split replays the body once per branch, so one scenario covers every path through a screen, and the flow in the picture above is exactly that. Store images, translation pictures and branch comparisons are all built from these runs.

Your agent gets the same tools #

The first launch adds an MCP server to your project's .mcp.json. Through it, an agent can render a preview to check a layout, run your scenarios and read what each screen showed, or launch the app on a simulator and tap through it, with every step it takes shown in the studio as it happens.

The same actions are on the command line:

alias fw='dart run flutterware'

fw run previews screenshot --entry='demo/shop.dart#shopMenu'
fw run scenarios run
fw run store export

Every action and option is listed in the capabilities reference.

Add it to your project #

dart pub add flutterware
dart run flutterware

Flutterware runs on the Dart SDK you start it with (fvm dart run flutterware works too) and never installs one of its own. The .mcp.json entry it writes runs plain dart from your PATH, so if a version manager picks your SDK, edit that entry to go through it (fvm dart run flutterware mcp). The first launch creates tool/flutterware.dart, where you pick your tools:

import 'package:flutterware/plugins.dart';

const app = Pkg('.');

void main() => Flutterware.configure((fw) {
  fw.use(Previews(packages: [.new(app)]));
  fw.use(Scenarios(packages: [.new(app, languages: ['en', 'fr'])]));
  fw.use(Dependencies(packages: [.new(app)]));
  fw.use(Assets(packages: [.new(app)]));
});

It's a plain Dart file, so the analyzer checks it and your editor completes it. For a monorepo, declare one Pkg per package and give each tool the ones it applies to. The demo's config is one app's; this repo's covers a workspace of several packages.

Libraries #

The package also ships libraries your app and tests can import. They work without the studio.

Get in touch #

If you use flutterware, are trying it out, or wonder whether it would fit your project, we'd love to hear from you. Questions, ideas, or something that got in your way: write to hello@flutterware.dev.

Contributing #

Issues and pull requests are welcome. CONTRIBUTING.md explains how to set up the repository.