xproject_generator 1.0.6

CLI and library to scaffold production-ready Flutter apps and feature modules using opinionated GetX, Riverpod, and Bloc templates.

XProject Generator

Scaffold production-ready Flutter apps and features in seconds

Opinionated, batteries-included templates for GetX, Riverpod, and Bloc — with flavors, localization, theming, token-refresh-ready networking, and beautiful starter screens out of the box.

Quick Start  •  Features  •  State Management  •  CLI  •  FAQ

---

Contents

Quick Start Features What you get State Management

CLI Reference Programmatic Usage Project Layout FAQ

---

Quick Start

# 1. Install the CLI globally from pub.dev
dart pub global activate xproject_generator

# 2. Create a new project (interactive)
xproject

# 3. Run it
cd <your_project_name>
flutter pub get
flutter run --flavor development -t lib/main_development.dart

The interactive wizard asks for app name, package IDs, Firebase, state management, architecture, and whether to encrypt .env files.

🚀 XProject - Flutter Project Generator

✔ App display name (e.g. Test App) · My App
✔ Project name (snake_case) · my_app
✔ Android package (e.g., com.example.app) · com.example.my_app
✔ iOS bundle ID · com.example.my_app
✔ Use Firebase? (Y/n): · n
✔ Select state management · Riverpod
✔ Select architecture · Clean Code
✔ Use Secret Key (Generator Package)? (Y/n): · y

---

Features

Scaffolding Interactive project wizard Add features to existing apps flutter create + dependency wiring .vscode tasks & launch configs

Architecture GetX, Riverpod, Bloc Simple or Clean Code layers DI-based, refresh-ready networking Single shared BaseConnection

Out of the box Flavors (dev / staging / prod) Localization (en / id) Light/dark theming + toggles Modern login & home screens

Networking & token refresh

BaseConnection (built on dio_extended) is provided through dependency injection instead of a global singleton, so a refreshed token is always picked up on the next request:

State management	How it's provided
Riverpod	baseConnectionProvider
GetX	Get.put<BaseConnection>(..., permanent: true)
Bloc	single resettable instance

A single, fresh instance lives for the entire app lifecycle and is shared everywhere. handleTokenExpired() is wired for automatic 401/402 retry.

Theming & localization

• App-wide theme and locale state with one-tap toggles on the home screen.
• Shared widgets read from Theme.of(context), so switching light/dark is reflected immediately.
• Explicit light/dark ColorScheme, input, button, and app-bar themes in theme/app_theme.dart.

Environment & secrets

• Generates .env.development, .env.staging, and .env.production.
• Optional "Use Secret Key" prompt: when enabled, .env files are encrypted via secure_compressor + a generated secret key; when disabled, plain .env loading is used.

---

State Management

Pick the flavor that fits your team. Riverpod and Bloc additionally let you choose Simple or Clean Code.

GetX

lib/features/<feature>/
├─ bindings/      # dependency wiring
├─ controllers/   # GetxController
├─ providers/     # data sources
├─ views/         # screens
└─ widgets/       # feature-local widgets (e.g. auth_scaffold, home_shell)

Riverpod (Simple / Clean Code)

lib/features/<feature>/
├─ data/
│  ├─ datasources/
│  ├─ models/
│  └─ repositories/        # Clean Code only
├─ domain/                 # Clean Code only
│  ├─ entities/
│  ├─ repositories/
│  └─ usecases/
└─ presentation/
   ├─ providers/
   ├─ views/
   └─ widgets/

Uses riverpod_annotation + riverpod_generator codegen for providers.

Bloc (Simple / Clean Code)

lib/features/<feature>/
├─ data/
│  ├─ datasources/
│  ├─ models/
│  └─ repositories/        # Clean Code only
├─ domain/                 # Clean Code only
│  ├─ entities/
│  ├─ repositories/
│  └─ usecases/
└─ presentation/
   ├─ bloc/                # bloc + event + state
   ├─ views/
   └─ widgets/

App-wide theme/locale handled by an AppCubit.

---

CLI Reference

Command	Description
xproject	Start the interactive project wizard
xproject create	Explicitly create a new project
xproject --feature <name>	Generate a feature in the current project
xproject -f <name>	Short form of --feature
xproject --version	Print the CLI version
xproject --help	Show help

# Add a feature — state management & architecture are auto-detected
xproject --feature authentication

When generating a feature, the tool detects your state management from pubspec.yaml/lib/ usage and your architecture from the presence of domain/ or data/repositories/ folders, then runs build_runner if codegen is needed.

---

What a generated project contains

• lib/ with app.dart, environment-specific main_*.dart, routes, theme, l10n, sessions, and core/
• lib/features/<feature>/ — views, controllers/notifiers/blocs, bindings/providers, and feature-local widgets
• .env.development, .env.staging, .env.production
• Android & iOS flavor configuration
• .vscode/ tasks and launch helpers

cd <your_project_name>
flutter pub get
# If using codegen (freezed / riverpod):
dart run build_runner build --delete-conflicting-outputs

---

Programmatic Usage (Dart)

The generators can also be used directly from Dart (illustrative):

import 'package:xproject_generator/xproject_generator.dart';
import 'package:xproject_generator/xfeature_generator.dart';

Future<void> main() async {
  // Create a new project (interactive by default)
  await ProjectGenerator().create();

  // Add a feature to an existing project
  await FeatureGenerator().add('authentication');
}

---

Project Layout

Path	Purpose
bin/xproject.dart	CLI entrypoint
lib/xproject_generator.dart	Interactive project generator
lib/xfeature_generator.dart	Feature generator for existing projects
lib/src/templates	Template code for GetX, Riverpod, and Bloc
pubspec.yaml	Package metadata

---

FAQ

I get a flutter pub get error about meta / analyzer on a Riverpod project

This happens when the Flutter stable SDK pins an older meta while the newest riverpod_generator requires a newer analyzer. Generated Riverpod projects pin a compatible codegen stack (riverpod_generator 4.0.3 with analyzer-9-compatible json_serializable/json_annotation) to avoid this. Make sure you're on a recent Flutter stable channel and run flutter pub get again.

How do I enable Firebase?

Answer yes to the Firebase prompt during creation, then add your platform files:

• android/app/google-services.json
• ios/Runner/GoogleService-Info.plist

The iOS flavor script lives at ios/firebase.sh; follow the on-screen Xcode steps printed after generation.

Can I switch state management after creating a project?

Not automatically — the scaffolding differs per state manager. Create a new project with the desired option, or migrate manually.

---

Contributing

Contributions are welcome. Keep changes small and focused, open issues for bugs or feature requests, and send pull requests for improvements to templates or tooling.

Made with Dart • Licensed under MIT