flutter_setup

A professional, end-to-end Flutter development, scaffolding, and release automation CLI package.

flutter_setup eliminates hours of setup and release overhead by scaffolding production-ready Flutter applications and automating the entire release lifecycle — from pre-flight validation and multi-environment builds to Shorebird OTA patching, Fastlane store deployment, Git release tracking, changelog generation, and Slack/Discord notifications.

---

📖 Table of Contents

• What is flutter_setup?
• Installation
• Quick Start
• Scaffolding & Code Generation
• Release Automation
  • Normal Flutter Release
  • Shorebird OTA Release
  • Shorebird OTA Patch
• Environments & Flavors
• Build Management
• Fastlane Store Deployment
• CI/CD & GitHub Actions
• Git Release Tracking & Tags
• Changelog & Release Notes
• Notifications & Integrations
• Dry-Run & Production Safety
• Recovery & Process Locking
• Exit Code Standardization
• Supported Platforms & Requirements
• Troubleshooting & Limitations

---

💡 What is flutter_setup?

flutter_setup bridges the gap between starting a new Flutter app and shipping it to production. It provides:

1. Architecture Scaffolding: Instantly creates clean Riverpod + Dio + GoRouter Flutter app skeletons with feature generators and automatic asset registration.
2. Release Orchestration: Coordinates version bumping, builds, Shorebird OTA releases, Fastlane deployment, Git tagging, changelogs, and webhook notifications through unified CLI commands.

---

⚡ Installation

Activate flutter_setup globally via pub.dev:

dart pub global activate flutter_setup

Verify installation:

flutter_setup --version

---

🚀 Quick Start

1. Create a new Flutter project

flutter_setup create my_awesome_app

2. Verify release readiness

cd my_awesome_app
flutter_setup verify

3. Run a dry-run release preview

flutter_setup release --environment staging --dry-run

---

🏗️ Scaffolding & Code Generation

flutter_setup includes generators to scaffold new projects or inject clean components into existing apps:

Command	Usage	Description
create	flutter_setup create [name]	Scaffolds a complete Flutter project
templates	flutter_setup templates	Lists available templates (default, minimal)
info	flutter_setup info <template>	View details for a template
feature	flutter_setup feature <name>	Scaffolds a complete feature module
screen	flutter_setup screen <name> --feature=<f>	Generates a Riverpod screen
model	flutter_setup model <name> --feature=<f>	Generates a data model class
repository	flutter_setup repository <name> --feature=<f>	Generates a repository pattern class
service	flutter_setup service <name> --feature=<f>	Generates an API service client

---

📦 Release Automation

flutter_setup supports three main release modalities:

1. Normal Flutter Release

Executes pre-flight validation, increments semver version, compiles Android AAB/APK or iOS IPA, records metadata, tags Git, and dispatches notifications:

flutter_setup release --mode normal --minor --environment production

2. Shorebird OTA Release

Executes a binary release through Shorebird CLI (shorebird release), creating a base release for future over-the-air patches:

flutter_setup release --mode shorebird --environment staging

3. Shorebird OTA Patch

Pushes an instant over-the-air Dart code patch without altering base version or native binary:

flutter_setup patch --environment production

---

🌍 Environments & Flavors

Supported target environments: development (dev), staging (stg), production (prod).

Flags:

• --environment or --env: Target environment name.
• --flavor: Target build flavor.
• --dart-define: Pass key-value definitions (--dart-define KEY=VAL).

Precedence resolution:

1. CLI flags
2. Environment variables (ENVIRONMENT, FLAVOR)
3. flutter_setup.yaml config
4. Fallback defaults

---

🛠️ Build Management

Build standalone artifacts without triggering full release tagging or store deployment:

flutter_setup build --platform android --format aab --flavor production
flutter_setup build --platform ios --format ipa

---

🚀 Fastlane Store Deployment

Deploy pre-built artifacts to Google Play or Apple App Store via Fastlane:

flutter_setup deploy --platform android --lane internal
flutter_setup deploy --platform ios --lane testflight

---

🤖 CI/CD & GitHub Actions

Generate production-ready GitHub Actions workflow manifests:

flutter_setup ci init --provider github
flutter_setup ci doctor

Generated workflows include secret redaction, concurrency scoping, matrix builds, Shorebird authentication, and Fastlane execution.

---

🏷️ Git Release Tracking & Tags

Track releases using Git tags and commit history:

flutter_setup release info
flutter_setup release history
flutter_setup release verify

Configurable tag prefix via --tag-prefix v or flutter_setup.yaml.

---

📝 Changelog & Release Notes

Automatically generate categorized release notes from commit history (feat:, fix:, docs:, refactor:):

flutter_setup release summary
flutter_setup release notes --format markdown
flutter_setup changelog --write

---

🔔 Notifications & Integrations

Send automated release notifications to team chat platforms:

flutter_setup notify --provider slack --message "Release v1.2.0 deployed to Staging"
flutter_setup notify --provider discord

Supported providers: github, slack, discord, webhook.

---

🛡️ Dry-Run & Production Safety

Preview execution steps without altering files, Git tags, or remote services:

flutter_setup release --environment production --dry-run

Production Safety Gates enforce:

• Prominent terminal warning summary for production targets.
• Clean Git working tree check (override with --allow-dirty).
• Version collision check against past release metadata.
• Tag collision check against Git repository.

---

🔒 Recovery & Process Locking

If a release crashes or deployment fails:

• Process Locking: Prevents concurrent releases via .flutter_setup/release.lock (with PID checks & 1-hour stale lock detection).
• State Inspection: flutter_setup release status
• Integrity Verification: flutter_setup release verify
• Safe Recovery: flutter_setup release recover or flutter_setup deploy --retry (re-uses verified artifacts without duplicate version bumps or tag creations).

---

🔢 Exit Code Standardization

Code	Meaning	Description
0	Success	Command executed cleanly
1	General Error	Unexpected runtime exception
2	Invalid Arguments	CLI argument parsing failure
3	Validation Error	Pre-flight validator check failed
4	Tool Unavailable	Required executable missing (Flutter, Git, Fastlane, Shorebird)
5	Build Failure	Compilation error during Flutter / Shorebird build
6	Deployment Error	Fastlane execution or store upload failed
7	Release Safety Violation	Production gate check or patch eligibility failed

---

🖥️ Supported Platforms & Requirements

• OS: macOS (required for iOS builds & Xcode), Linux, Windows.
• Dart SDK: >=3.0.0 <4.0.0
• Flutter SDK: 3.10.0+
• External Tools: git, flutter, fastlane (optional), shorebird (optional).

---

❓ Troubleshooting & Limitations

• iOS Builds on Windows/Linux: iOSIPA compilation requires Xcode and macOS. flutter_setup detects host OS and provides clear early errors if iOS builds are attempted on unsupported platforms.
• Fastlane Setup: Fastlane must be installed and configured in android/fastlane or ios/fastlane.
• Shorebird Authentication: Ensure SHOREBIRD_TOKEN is exported in your environment or active in Shorebird CLI.

---

📄 License

Licensed under the MIT License.