xproject_generator 1.1.1

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

# The CLI shows step progress (0–100%) while scaffolding, then runs
# flutter pub get + build_runner in the project for you.

# 3. Finish setup using GUIDE.md, then run
cd <your_project_name>
flutter run --flavor development -t lib/main_development.dart

The interactive wizard asks for app name, package IDs, platform targets, state management, architecture (Bloc/Riverpod), Firebase, secret key, and optional CI/CD (GitLab or GitHub; test-only or deploy via Fastlane; GitLab supports shared, Docker, or self-hosted shell runners e.g. Mac Mini). GUIDE.md is an English setup guide.

🚀 XProject - Flutter Project Generator

… wizard prompts …

📦 ⠹ Creating Flutter project...                         18%
✓ 📦 Creating Flutter project...                      (2.1s)
📁 ⠼ Generating project structure...                    42%
✓ ⚙ Resolving packages and running code generation...  (15.3s)

✅ Project created successfully

---

Features

Scaffolding Interactive project wizard (platform target, optional GitLab CI or GitHub Actions) Create progress — four steps with spinner, icon, and overall 0–100%; step duration when done Post-create — flutter pub get + build_runner in the new project Add features to existing apps flutter create --platforms + dependency wiring .vscode tasks & launch configs (run/build per flavor) GUIDE.md — English setup guide (checklists; TOC links work in VS Code preview)

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 setup	Menu of integrations not yet installed (run inside the project)
xproject setup firebase	Add Firebase after create answered no
xproject setup secret-key	Turn on encrypted .env loading (setup secret is the same)
xproject setup ci	Add GitLab CI or GitHub Actions (setup cicd is the same)
xproject setup platforms	Add Flutter platforms that were not selected at create
xproject setup guide	Regenerate GUIDE.md (English)
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.

Setup commands read the current project (name, package, state management, platforms, and which integrations are already on). They do not ask those questions again. Run them from the generated app directory:

cd <your_project_name>
xproject setup                 # menu
xproject setup firebase        # only if create answered no to Firebase
xproject setup secret-key
xproject setup ci
xproject setup platforms
xproject setup guide           # regenerate GUIDE.md only

setup firebase does not replace a google-services.json or GoogleService-Info.plist you already downloaded. setup secret-key does not rewrite .env.* and does not invent a real secret; it writes a stub lib/core/config/secretkey.dart that throws until you replace it. setup ci asks before overwriting an existing pipeline. After setup, GUIDE.md is regenerated and the CLI notes which integration was updated (checklist in Part 2).

---

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
• GUIDE.md — English setup guide; regenerated after xproject setup
• README.md (in generated project) — quick pointer to GUIDE.md
• Optional CI/CD: .gitlab-ci.yml + ci/Dockerfile (GitLab) or .github/workflows/flutter_ci.yml (GitHub Actions), plus fastlane/ when deployment is enabled
• Android & iOS flavor configuration
• .vscode/ tasks and launch helpers

cd <your_project_name>
# pub get + build_runner already ran during `xproject create`; repeat only if needed:
# flutter pub get
# dart run build_runner build --delete-conflicting-outputs

Follow GUIDE.md for env files, flavors, Firebase, and the rest. Quick run after checklist:

flutter run --flavor development -t lib/main_development.dart

Or use Run and Debug in VS Code ([DEV] / [STG] / production) as described in GUIDE Part 2.

---

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';
import 'package:xproject_generator/xsetup_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');

  // Add an integration that was skipped at create time.
  // Run with the working directory set to that Flutter project.
  await SetupGenerator().firebase();
  await SetupGenerator().secretKey();
  await SetupGenerator().ciCd();
  await SetupGenerator().platforms();
  await SetupGenerator().regenerateGuide();
}

---

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/xsetup_generator.dart	Post-create Firebase, secret key, CI/CD, and platforms
lib/src/post_create_codegen.dart	flutter pub get + build_runner after create
lib/src/cli_step_progress.dart	Terminal progress during create
lib/src/templates	Template code for GetX, Riverpod, and Bloc
CHANGELOG.md	Version history (latest 1.1.1)
pubspec.yaml	Package metadata

---

FAQ

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

This usually means an outdated Flutter SDK or a stale pubspec.lock. Generated Riverpod projects use riverpod_generator ^4.0.9 with build_runner ^2.16.0 (newer build_runner 2.17+ is not yet compatible with riverpod_generator). Upgrade Flutter stable, delete pubspec.lock, then run flutter pub get again.

How do I enable Firebase?

Answer yes to the Firebase prompt during creation, or from the project directory run:

xproject setup firebase

Then replace the placeholders (these files are not overwritten if they already exist):

• android/app/src/<flavor>/google-services.json for development, staging, and production
• ios/config/<flavor>/GoogleService-Info.plist

The iOS flavor script lives at ios/firebase.sh. In Xcode, add a Run Script phase that runs it before Copy Bundle Resources. xproject setup secret-key and xproject setup ci cover the other optional prompts from create.

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.

Android build fails after upgrading to AGP 8+ / 9+ (custom resource values disabled)

Newer Android Gradle Plugin versions disable resValue() generation unless you enable it. Generated projects include buildFeatures { resValues = true } (or resValues true in Groovy) and set android:label="@string/app_name" in the manifest so flavor-specific app names work.

If you created a project with an older generator version, add the same buildFeatures block to android/app/build.gradle(.kts) and point the manifest label at @string/app_name.

Built-in Kotlin (AGP 9) and gradle.properties flags

Generated Android projects follow Flutter’s built-in Kotlin migration for app developers: the :app module does not apply the Kotlin Gradle Plugin directly, and uses kotlin { compilerOptions { … } } with JVM 17 when the Flutter template provides it.

android/gradle.properties includes android.newDsl=false and android.builtInKotlin=false (Flutter’s transitional default). After your app and its Flutter plugins support built-in Kotlin, set android.builtInKotlin=true and run flutter build apk to validate. If a plugin still applies KGP and breaks the build, use the report template on the plugin’s repository.

---

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