flutterflow_flash_beta 0.1.3

Dart SDK for programmatically reading and modifying FlutterFlow projects. Built for the beta environment.

Flash by FlutterFlow

Flash is the AI-native, code-powered companion to FlutterFlow.

Use FlutterFlow's visual builder when it is the fastest tool for the job, and use Flash when you want reviewable code, local validation, repeatable changes, and agent-friendly workflows for new or existing apps.

Why Flash

Flash helps you:

• build new FlutterFlow apps in Dart
• make larger or more precise changes to existing FlutterFlow apps
• validate locally before pushing changes
• inspect existing pages, components, and resources before editing
• keep FlutterFlow development in source control
• give human developers and AI agents the same structured workspace

Flash is not a replacement for FlutterFlow's visual-first workflow. It complements it.

Think of the model as:

• FlutterFlow for visual speed
• Flash for code precision, repeatability, and AI-native workflows

Who Flash Is For

FlutterFlow developers

Flash is useful when you want to:

• create reviewable changes instead of editor-only diffs
• work faster on repetitive or structured changes
• inspect a project before editing it
• keep a reliable local workflow with validation, traces, and history

AI-driven builders

Flash is useful when you want to:

• let agents work in a real code workspace instead of an opaque visual-only surface
• generate or refine app changes in Dart
• keep the workflow deterministic, reviewable, and easy to hand off
• combine FlutterFlow's visual builder with agent-friendly development

Install

Install the CLI:

dart pub global activate flutterflow_flash_beta

If you want to use Flash as a library in a Dart package:

dart pub add flutterflow_flash_beta

Requirements:

• Dart 3.7+
• A FlutterFlow API key

Authentication options:

• Put FF_API_KEY=<your-key> in .env
• Or pass --api-key <your-key> to Flash commands

Example .env:

FF_API_KEY=your-key-here

Quickstart

Create a new Flash workspace:

flash init my-app
cd my-app
cp .env.example .env
dart pub get
dart test
flash validate flash/app.dart
flash run flash/app.dart --project-name "My App" --commit-message "Initial app"

That gives you a ready-to-edit workspace with:

• flash/app.dart for building a new app
• flash/brownfield_patch.dart for changes to an existing app
• references/ with working DSL examples
• patterns/ with existing-app helper patterns
• tooling/ wrapper scripts for common flows
• AGENTS.md and CLAUDE.md for agent handoff

Important: use flash/app.dart for the first push of a new app. After the project exists, switch to flash/brownfield_patch.dart and run flash refresh-context <project-id> before deeper work. Use --find-or-create only when retrying a run that may already have created the remote project.

What The Workflow Looks Like

The core loop is simple:

1. Build a new app or start from an existing FlutterFlow project.
2. Describe the app or change in Dart.
3. Run flash validate locally.
4. Push with flash run.
5. Continue iterating in Flash, in FlutterFlow, or both.

This makes Flash a good fit when you want to combine:

• FlutterFlow's visual editing speed
• code review and source control
• repeatable automation
• AI-assisted development

Build A New App

Here is a small but real Flash app definition:

import 'package:flutterflow_flash_beta/flutterflow_flash.dart';

void buildStarterApp(App app) {
  app.themeColor('primary', 0xFF0B57D0);
  app.themeColor('primaryBackground', 0xFFF7F9FC);
  app.primaryFont('Inter');

  app.page(
    'StarterPage',
    route: '/',
    isInitial: true,
    description: 'Simple starter page for a new Flash app.',
    body: Scaffold(
      appBar: AppBar(title: 'Flash Demo'),
      body: Container(
        padding: 24,
        child: Column(
          spacing: 16,
          crossAxis: CrossAxis.start,
          children: [
            Text('Build FlutterFlow apps with Dart', style: Styles.headlineSmall),
            Text(
              'Flash makes FlutterFlow changes reviewable, repeatable, and agent-friendly.',
              style: Styles.bodyMedium,
              color: Colors.secondaryText,
            ),
            Button(
              'Show Snackbar',
              width: double.infinity,
              onTap: Snackbar('Flash is wired correctly.'),
            ),
          ],
        ),
      ),
    ),
  );
}

Run it with:

flash validate flash/app.dart
flash run flash/app.dart --project-name "Flash Demo" --commit-message "Create starter page"

Work On An Existing FlutterFlow App

Flash is also built for existing apps, whether you are making focused changes or adding larger new flows.

Start from an existing project:

flash init my-edits --project <project-id>
cd my-edits
cp .env.example .env
dart pub get
flash inspect <project-id> --page HomePage
flash validate flash/brownfield_patch.dart --project-id <project-id>
flash run flash/brownfield_patch.dart --project-id <project-id> --commit-message "Update HomePage"

Useful existing-app commands:

• flash inspect <project-id> to fetch machine-readable project structure
• flash resources <project-id> to inspect reusable project and library resources
• flash refresh-context <project-id> to regenerate local project context docs
• flash context-check to see whether your local context is stale

Recommended rule for existing apps: inspect first, then make changes.

CLI Workflow

The commands most developers use are:

flash init <name> [--project <id>]
flash doctor
flash precache
flash validate <file> [--project-name <name> | --project-id <id>]
flash run <file> [--project-name <name> | --project-id <id>]
flash inspect <project-id> [--page <name> | --component <name>]
flash resources <project-id>
flash refresh-context <project-id>
flash context-check
flash history
flash trace latest
flash support inspect <run-id>

flash validate is a dry run. It compiles and validates the DSL program without pushing changes to FlutterFlow.

flash doctor shows the installed Flash version, the current proto fingerprint, and whether the matching local validator binary is already cached for your platform.

flash precache downloads that validator ahead of time, so later flash validate and flash run calls can use the local validator immediately instead of fetching it on first use.

Agent-Friendly By Design

Flash works well for direct human use, but its workspace model is especially useful when you want agents involved in the workflow.

After flash init, the generated workspace already includes:

• instructions in AGENTS.md and CLAUDE.md
• reference DSL apps in references/
• common existing-app patterns in patterns/
• wrapper scripts in tooling/
• local run history and traces in .flash/

Typical agent handoff:

1. Run flash init ...
2. Add FF_API_KEY to .env
3. Ask the agent to read AGENTS.md
4. Have it edit flash/app.dart or flash/brownfield_patch.dart
5. Require flash validate before flash run

Learn By Reference

Start with the closest working example instead of writing a DSL from scratch.

• shopflow_dsl.dart
• taskboard_dsl.dart
• auth_shell_dsl.dart
• supabase_crud_auth_shell_dsl.dart
• social_feed_data_dsl.dart
• workflow_forms_dsl.dart
• commerce_shell_dsl.dart
• content_companion_dsl.dart
• resource_library_dsl.dart
• postgres_compile_only_dsl.dart
• action_block_showcase_dsl.dart
• app_event_showcase_dsl.dart
• genui_catalog_assistant_dsl.dart
• local_state_crud_dsl.dart
• styled_profile_dsl.dart
• media_browser_dsl.dart
• brownfield_add_search_filter_dsl.dart
• brownfield_form_and_detail_dsl.dart
• brownfield_restyle_and_enhance_dsl.dart
• multi_api_call_dsl.dart

All of these live under specs/dsl/.

More Docs

Read the package docs directly:

• Concepts
• CLI Reference
• MCP Guide
• Troubleshooting
• Support Playbook

Or use the built-in docs commands:

• flash docs readme
• flash docs concepts
• flash docs cli
• flash docs mcp
• flash docs troubleshooting
• flash docs agent-setup
• flash docs api-surface