fstack_cli 1.0.1

A modern Flutter scaffolding CLI that builds production-ready architecture in seconds.

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_cli_config.json—so subsequent commands remain consistent.

Table of contents

1. Requirements
2. Installation
3. Quick start
4. Command reference
5. Template library
6. Configuration
7. Workflow tips
8. Example output
9. Troubleshooting
10. Contributing
11. License

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_cli from anywhere.

If the fstack_cli command is not found

Dart installs global executables inside the Pub cache folder. If your terminal cannot find the fstack_cli command after activation, add the Pub cache bin to your PATH.

macOS / Linux

Add this line to your shell config (~/.zshrc, ~/.bashrc, etc.):

export PATH="$PATH:$HOME/.pub-cache/bin"

Then reload your terminal session:

source ~/.zshrc

Windows

Add the following path to Environment Variables → User PATH:

%USERPROFILE%\AppData\Local\Pub\Cache\bin

You may need to restart your terminal (or Windows) after updating PATH.

Verify installation

fstack_cli --help

Quick start

fstack_cli create my_app

You will confirm state management, API client, localization, and theme support during create. Those answers are saved in fstack_cli_config.json and automatically applied to every future fstack_cli 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

Command	Description	Key Flags
fstack_cli create <name>	Runs flutter create, injects selected architecture, writes fstack_cli_config.json.	-f/--force overwrite existing folder
fstack_cli make module <name>	Generates a feature module wired to the chosen state manager.	-f/--force
fstack_cli make model <name>	Createsa data model withcopyWith`, timestamps, metadata, and JSON helpers.	-f/--force
fstack_cli make widget <name>	Produces a Material 3-friendly widget scaffold.	-f/--force
fstack_cli make service <name>	Places a neutral service under lib/data/services.	-f/--force
fstack_cli make handler <name>	Generates UX-friendly success/error handler helpers.	-f/--force
fstack_cli make page <name>	Adds a routed page scaffold consistent with localization/theme toggles.	-f/--force

Additional notes:

• Commands search upward from the current directory until they find fstack_cli_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_cli_config.json lives at the project root and is created during fstack_cli 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_cli 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

Issue	Resolution
Unable to locate fstack_cli_config.json	Run fstack_cli create first or ensure you are inside a project generated by the CLI. Commands search parent directories automatically.
flutter / dart not found	Install Flutter 3.x (with Dart 3.x) and add it to your PATH. Confirm with flutter --version.
Want to regenerate a file	Re-run the relevant fstack_cli make … command with --force.
Need different stack per project	Each project keeps its own fstack_cli_config.json. Just run fstack_cli create again in a new folder with different options.
Want manual control	Simply edit the generated files. The CLI won't overwrite them unless --force is used.

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.