flutter_archgen

flutter_archgen is a Dart CLI package that scaffolds a production-minded Flutter architecture with:

  • app, core, shared, and placeholder features layers
  • flutter_riverpod, get_it, and injectable setup
  • an always-on dio networking stack
  • optional Firebase, Crashlytics, Sentry, notifications, Hive, SQLite, device info, Shorebird, and Fastlane modules
  • generator-owned file markers so reruns stay predictable

What It Generates

Inside the target Flutter app, the generator creates or updates:

  • lib/main.dart
  • lib/app/**
  • lib/core/**
  • lib/shared/**
  • lib/features/README.md
  • test/architecture_smoke_test.dart
  • build.yaml
  • analysis_options.yaml
  • the target app pubspec.yaml
  • a generated README section if the app README already exists
  • sentry.properties.example when Sentry is enabled
  • tool/release/shorebird/** and shorebird.yaml.example when Shorebird is enabled
  • fastlane/** and Gemfile when Fastlane is enabled

The generated app includes:

  • startup bootstrap and environment loading
  • feature-safe placeholder routing
  • AppEnv, flavors, and compile-time config
  • get_it + injectable dependency wiring
  • a reusable Dio HTTP client with auth, logging, retry hooks, validation, and error mapping
  • shared preferences and secure storage services
  • optional Firebase bootstrap, Crashlytics, Sentry, notifications, Hive, SQLite, device info, Shorebird, and Fastlane release scaffolding

Install

Add the package to a Flutter app:

dev_dependencies:
  flutter_archgen: ^0.1.0

Then run:

flutter pub get
dart run flutter_archgen:init --app-name MyApp

You can also use the command-runner entrypoint:

dart run flutter_archgen init --app-name MyApp

Basic Usage

Generate the default architecture:

dart run flutter_archgen:init --app-name Orbit

Generate with common optional modules:

dart run flutter_archgen:init \
  --app-name Orbit \
  --org com.example.orbit \
  --flavors dev,staging,prod \
  --firebase \
  --crashlytics \
  --sentry \
  --remote-config \
  --notifications \
  --device-info \
  --hive \
  --sqlite \
  --shorebird \
  --fastlane

Flags

Flag Purpose
--app-name Sets the generated default app name used by AppEnv.
--org Reserved for future platform tooling helpers.
--flavors Comma-separated flavor names. Use lowercase letters, numbers, and underscores only.
--firebase Adds Firebase core wrappers and dependencies.
--crashlytics Adds Firebase Crashlytics dependencies and bootstrap hooks. Implies Firebase support.
--sentry Adds Sentry monitoring services, env hooks, and sentry.properties.example.
--remote-config Adds Firebase Remote Config service generation. Implies Firebase support.
--notifications Adds local notification scaffolding and optional Firebase messaging dependency when Firebase is enabled.
--device-info Adds a device info service scaffold.
--hive Adds Hive cache service generation with CRUD helpers.
--sqlite Adds SQLite database service generation with CRUD helpers.
--shorebird Adds Shorebird release setup docs and template config files.
--fastlane Adds Fastlane automation scaffolding with a Gemfile, Appfile, and Fastfile.
--force Overwrites user-owned files in addition to generator-owned files.
--skip-pub-get Skips the reminder to run flutter pub get after generation.
--target-dir Generates into a specific Flutter app directory. Defaults to the current directory.

Generator Rules

  • The target must be a Flutter app with dependencies.flutter.sdk: flutter.
  • Flavor names are validated before generation to avoid invalid Dart enums.
  • Files marked Generated by flutter_archgen. are safe to refresh on reruns.
  • User-owned files are not overwritten unless --force is used.
  • The Dio networking layer is always generated because the scaffold depends on it.

Run these commands inside the generated Flutter app:

flutter pub get
dart run build_runner build
flutter analyze

Then replace the placeholder routes and add your feature modules.

Firebase Setup

If you enabled --firebase, --remote-config, or --crashlytics:

  1. Add the app to Firebase.
  2. Run flutterfire configure from the generated Flutter app.
  3. Add the generated Firebase config files for each supported platform.
  4. If you enabled Crashlytics, rerun flutterfire configure after adding Crashlytics so platform setup stays in sync.
  5. If you want to use DefaultFirebaseOptions.currentPlatform, wire that into bootstrap after flutterfire configure generates firebase_options.dart.

Shorebird Setup

When --shorebird is enabled, the generated app adds:

  • tool/release/shorebird/README.md
  • shorebird.yaml.example

To finish setup:

  1. Install the Shorebird CLI.
  2. Run shorebird init.
  3. Copy placeholder values from shorebird.yaml.example into your real Shorebird config.
  4. Run the generated Shorebird commands with your release flavor, usually prod.

Fastlane Setup

When --fastlane is enabled, the generated app adds:

  • Gemfile
  • fastlane/Appfile
  • fastlane/Fastfile
  • fastlane/README.md

To finish setup:

  1. Install Ruby and Bundler.
  2. Run bundle install.
  3. Fill in real identifiers and team settings in fastlane/Appfile.
  4. Store upload credentials in CI environment variables rather than the repository.

Crashlytics Setup

When --crashlytics is enabled, the generated app:

  • initializes Firebase before runApp
  • enables Crashlytics collection through AppEnv
  • records framework and platform-level uncaught errors
  • sets basic custom keys like app name and flavor

You still need to complete Firebase platform configuration in the actual app for Crashlytics to report correctly.

Sentry Setup

When --sentry is enabled, the generated app:

  • initializes Sentry early in bootstrap
  • wires SentryNavigatorObserver into MaterialApp
  • forwards breadcrumbs and monitored exceptions through the shared monitor abstraction
  • adds sentry.properties.example

To finish setup in the generated app:

  1. Set SENTRY_DSN through --dart-define or your build system.
  2. Copy sentry.properties.example to sentry.properties.
  3. Fill in your real Sentry org, project, and auth token.
  4. Run dart run sentry_dart_plugin after release builds if you use Sentry symbol upload automation.

Environment Variables in Generated Apps

The generated app reads compile-time values such as:

  • APP_NAME
  • FLAVOR
  • API_BASE_URL
  • CONNECT_TIMEOUT_MS
  • RECEIVE_TIMEOUT_MS
  • SEND_TIMEOUT_MS
  • ENABLE_VERBOSE_LOGS
  • ENABLE_SENTRY
  • ENABLE_CRASHLYTICS
  • SENTRY_DSN
  • SENTRY_TRACES_SAMPLE_RATE

Example:

flutter run \
  --dart-define=APP_NAME=Orbit \
  --dart-define=FLAVOR=dev \
  --dart-define=API_BASE_URL=https://api.example.com \
  --dart-define=ENABLE_SENTRY=true \
  --dart-define=SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

Development

dart pub get --no-example
dart test
dart analyze

Notes on Robustness

The generator has been tuned to avoid a few common failure modes:

  • invalid flavor names are rejected before files are written
  • generation aborts early for non-Flutter targets
  • optional modules only inject their imports and registrations when enabled
  • generated device info and multipart helpers avoid dart:io assumptions where possible for better cross-platform safety
  • reruns are safe for generator-owned files and conservative for user-owned files

Libraries

flutter_archgen