flutter_archgen 0.1.1

Generates a feature-safe Flutter architecture shell with Riverpod, GetIt, Injectable, and Dio.

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, and device info 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

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, and device info services

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

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.
--sqlite	Adds SQLite database service generation.
--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.

Recommended Workflow After Generation

Run these commands inside the generated Flutter app:

flutter pub get
dart run build_runner build --delete-conflicting-outputs
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.

The generated AppFirebaseService is intentionally minimal. If you want to use DefaultFirebaseOptions.currentPlatform, wire that into the bootstrap after flutterfire configure generates firebase_options.dart.

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://[e-mail]/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