flutterstart 0.3.3

A review-first CLI for creating deterministic, production-ready Flutter projects.

FlutterStart

Create your Flutter project, your way.

FlutterStart is a review-first CLI that generates deterministic, production-ready Flutter projects. Nothing is written to disk until you have seen the exact plan and explicitly approved it. Every choice — architecture, state management, routing, and the full application foundation — is resolved from a versioned Capability Catalog with catalog-driven compatibility checks, so the same inputs always produce the same project.

Current release: 0.3.0 — deterministic, review-first project creation with a configurable Application Foundation.

Installation

dart pub global activate flutterstart

Make sure the pub global bin directory is on your PATH, then confirm:

flutterstart doctor

Quick start

# 1. Check your environment is ready to generate
flutterstart doctor

# 2. Create a project interactively — pick a setup mode, review, approve
flutterstart create my_app

create walks you through:

1. Environment preflight — Flutter/Dart toolchain health.
2. Setup mode — Recommended, Customize, or Minimal.
3. Configuration — identity plus any capability selections.
4. Compatibility — catalog-driven validation of your selections.
5. Plan review — the full list of files and operations, with the destination still untouched.
6. Approval — type yes to materialize the project.

How it works

FlutterStart never mutates your destination directly. It stages the project in a temporary location, produces a reviewable Change Plan, and only writes to the destination after explicit approval. You can split review and apply:

# Produce a reviewable plan and stop
flutterstart create my_app --plan

# Inspect it
flutterstart plan show <planId>

# Apply only after explicit approval
flutterstart apply <planId> --approve <planId>

# Or throw it away
flutterstart plan discard <planId>

Commands

Command	Description
flutterstart doctor	Report Flutter/Dart toolchain and environment health.
flutterstart create <name>	Build a reviewable project plan and optionally apply it.
flutterstart plan show <planId>	Render a persisted Change Plan for review.
flutterstart plan discard <planId>	Discard a persisted Change Plan.
flutterstart apply <planId> --approve <planId>	Apply an explicitly approved Change Plan.
flutterstart validate	Validate a generated FlutterStart project.

create options

Option	Purpose
--plan	Stop after saving a reviewable plan (no apply).
--config <file>	Resolve the Blueprint from a versioned YAML config file.
--non-interactive	Fail instead of prompting when a decision is missing.
--output text|json	Select human or machine-readable output.
--description <text>	Project description.
--organization <id>	Reverse-DNS organization identifier (e.g. com.example).
--destination <path>	Output directory.
--platform <name>	Target platform; repeat for several (android, ios, web, macos, windows, linux).
--git yes|no	Initialize a git repository.
--validation-profile standard	Post-apply validation profile.

Setup modes

Mode	What it does
Recommended	Applies a curated, production-ready stack after you review project identity.
Customize	Opens the full section-based configurator, including the optional Application Foundation.
Minimal	A lean baseline with the smallest set of opinionated defaults.

All three modes converge on the same schema_version: 3 Blueprint.

Application Foundation

Customize mode presents one optional Application Foundation section. Every capability is single-select and independently skippable, and the section as a whole can be skipped. Skipped capabilities are absent from the Blueprint — no none sentinel is stored, so "None" and "skip" are identical.

Capability	Options
App Initialization	Simple · Bootstrap · Production Bootstrap Pipeline
Environment Configuration	Dart Define · Flutter Dotenv · Envied
Flavors	Basic · Advanced
Logging	Logger · Talker
Error Handling	Basic · Failure / Result Pattern · Global Error Boundary
Theme System	Basic ThemeData · Material 3 · Design Tokens
Localization	Flutter gen-l10n · Easy Localization
Project Structure	Feature First · Layer First · Hybrid

Project Structure is storage-only in 0.3. The convention is validated and stored in the Blueprint but does not change generated files yet — feature generation consumes it from 0.4 on, so output is identical across the three choices today.

Project Organization

The Release 0.2 capability selections remain available in Customize mode:

Capability	Options
Architecture	Simple · Clean Architecture
State Management	Bloc / Cubit · Riverpod · setState / Minimal
Routing	GoRouter · Navigator / Minimal · Skip
Backend	REST with Dio · REST with package:http · Supabase
Local Storage	SharedPreferences · Flutter Secure Storage · Drift / SQLite
Data Modeling	freezed + json_serializable · json_serializable only · Manual models
Dependency Injection	GetIt · Riverpod-based · Manual injection

Some options carry compatibility prerequisites (platform support, code generation) that are surfaced during validation. Options declared but not yet generatable (e.g. a Firebase backend) are not selectable.

Non-interactive configuration

Drive create from a versioned YAML config file for CI and reproducible setups:

schema_version: 3
project_name: demo_app
description: A demo app.
organization: com.example
destination: demo_app
target_platforms: [android, ios]
git: true
setup_mode: customize
single_selections:
  # Application Foundation
  foundation.app_initialization: bootstrap
  foundation.logging: logger
  foundation.error_handling: global_boundary
  foundation.project_structure: feature_first
  # Project Organization
  org.state_management: bloc
  org.routing: go_router
  org.dependency_injection: get_it

flutterstart create demo_app --config demo_app.yaml --plan

Migration: version 1 and 2 config files upgrade on read, and relocated Organization/Localization selections retain stable IDs. In version 3 the retired org.project_organization and org.localization keys are rejected with a structured LEGACY_RELOCATED_KEY error rather than silently remapped.

JSON output

Every command accepts --output json and emits a stable envelope suitable for scripting and CI:

flutterstart create my_app --config my_app.yaml --plan --output json

The create plan envelope includes the resolved Blueprint, structured compatibility findings (status + per-finding severity/code/message), and the list of target paths — all before anything is written.

Exit codes

Code	Meaning
0	Success
1	Unexpected internal error
2	Usage error (invalid arguments)
3	Environment preflight failure
4	Blueprint invalid or compatibility blocker
5	Planning or staging failure
6	Plan not found, or state forbids the operation
7	Plan stale, or staging integrity failure
8	Approval required and absent
9	Apply failed — rolled back
10	Apply failed — partial or manual recovery required
11	Validation failed
12	Cancelled by user
13	Session lock held by another FlutterStart operation

Supported platforms

• macOS & Linux — supported release targets, enforced by blocking CI gates.
• Windows — Provisional and non-blocking.

Roadmap

Upcoming releases (not yet available):

• 0.4 — Feature generation. Generate features and folder structures from the Project Structure convention stored in 0.3.
• Visual web configurator.
• Authentication starter.
• CI/CD templates.

Repository

https://github.com/MohamedAbd0/flutterstart