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

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