fstack_cli #

A professional Flutter scaffolding CLI that bootstraps production-ready architecture in minutes.

fstack_cli streamlines greenfield Flutter projects and keeps large teams aligned by generating feature modules, models, widgets, handlers, and services that follow your chosen stack (state management, API client, localization, theming). All generators respect a single source of truth—fstack_config.json—so subsequent commands remain consistent.

Requirements #

• Flutter 3.x (bundled with Dart >=3.0.0 <4.0.0).
• flutter & dart available on your PATH.
• macOS, Linux, or Windows shell access.

Installation #

Global activation is the recommended path:

dart pub global activate fstack_cli

Ensure ~/.pub-cache/bin is on your PATH, then run fstack from anywhere. (During CLI development you can also run dart run bin/fstack_cli.dart … directly.)

Quick start #

fstack create my_app
cd my_app
fstack make model user_profile

You will confirm state management, API client, localization, and theme support during create. Those answers are saved in fstack_config.json and automatically applied to every future fstack make … command.

Note: my_app is used purely as an example throughout this README. Replace it with your real project name. Each generated app ships with its own README that explains the resulting structure.

Command reference #

Additional notes:

• Commands search upward from the current directory until they find fstack_config.json, so you can run them anywhere inside your repo.
• Auto-formatting runs after every file write. Your workspace stays aligned with dart format.
• Templates safeguard against overwriting; opt into regeneration with --force.

Template library #

• Feature modules (lib/modules/<feature>/): state-management-specific providers/blocs/cubits plus Material 3 views with localization hooks.
• Models (lib/data/model): immutable classes featuring copyWith, updatedAt, optional metadata maps, and fromJson/toJson. Equatable-free per user feedback.
• Widgets (lib/core/widgets): polished neutral components that showcase best practices (layout spacing, typography, placeholders).
• Services (lib/data/services): infrastructure-agnostic service classes ready for dependency injection or manual Http/Dio wiring.
• Handlers (lib/core/handlers): convenience classes exposing showError/showSuccess with guidance comments about plugging into logging/analytics/snackbars/dialogs.
• Pages (lib/modules/<feature>/view or lib/pages depending on setup): screens that respect localization, router wiring, and theme toggles.

Every generator merely provides a head start. You remain free to edit scaffolds manually; rerun the command with --force if you ever need to snap back to the template.

Configuration #

fstack_config.json lives at the project root and is created during fstack create:

{
  "schemaVersion": 1,
  "projectName": "my_app",
  "stateManagement": "cubit",
  "apiClient": "dio",
  "withLocalization": true,
  "withTheme": true
}

This file is the single source of truth. Do not edit manually unless you are intentionally changing the project stack. All make commands read it automatically.

Workflow tips #

1. Stay inside the project root: Run fstack make … from the project or any subdirectory—it will traverse upward until it finds the config file.
2. Manual edits encouraged: Templates are intentionally neutral. Modify generated files to match your business logic. The CLI will not overwrite them unless you pass --force.
3. Version control friendly: Because files are formatted immediately, diffs remain clean and reviewers can focus on logic rather than style.
4. Local README per project: Every newly generated project includes a README summarizing the module structure so newcomers can onboard quickly.

Example output #

Example snippet from a BLoC + localization + theme-aware main.dart:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final sharedPrefs = await SharedPreferences.getInstance();
  final localeBloc = LocaleBloc();
  runApp(MyApp(sharedPrefs: sharedPrefs, localeBloc: localeBloc));
}

class MyApp extends StatelessWidget {
  final SharedPreferences sharedPrefs;
  final LocaleBloc localeBloc;

  const MyApp({super.key, required this.sharedPrefs, required this.localeBloc});

  @override
  Widget build(BuildContext context) {
    return MultiBlocProvider(
      providers: [
        BlocProvider(create: (_) => ThemeBloc(sharedPrefs)),
        BlocProvider.value(value: localeBloc),
      ],
      child: BlocBuilder<ThemeBloc, ThemeState>(
        builder: (context, themeState) {
          return MaterialApp.router(
            title: 'my_app',
            routerConfig: AppRouter.router,
            theme: AppTheme.lightTheme,
            darkTheme: AppTheme.darkTheme,
            themeMode: themeState.mode,
            locale: context.watch<LocaleBloc>().state.locale,
            localizationsDelegates: const [
              AppLocalizations.delegate,
              GlobalMaterialLocalizations.delegate,
              GlobalCupertinoLocalizations.delegate,
              GlobalWidgetsLocalizations.delegate,
            ],
            supportedLocales: const [Locale('en'), Locale('fr')],
          );
        },
      ),
    );
  }
}

Troubleshooting #

Contributing #

1. Fork the repository.
2. Run dart format . && dart analyze before committing.
3. Add/adjust tests or the example/ project when adding features.
4. Open a PR describing the change and attach CLI screenshots or text output when relevant.

License #

MIT License. See LICENSE for details.