When to use Moarch
Moarch is a command‑line utility designed to eliminate the repetitive boilerplate that often slows down the start of a new Flutter project. By generating a complete clean‑architecture skeleton, Moarch gives developers a ready‑to‑run codebase that follows proven separation‑of‑concerns patterns, integrates a state‑management solution of choice (Riverpod or flutter_bloc), and respects the Flutter Version Management (FVM) workflow. The generated project includes feature, data, and domain layers, a well‑structured folder hierarchy, and a set of starter files that demonstrate best practices for dependency injection, testing, and navigation. This approach helps teams enforce a consistent architecture from day one, reducing the risk of architectural drift as the codebase grows.
When to use Moarch? It shines in scenarios where a team wants to adopt clean architecture but lacks a shared template or when a solo developer wants to jump straight into building UI without spending hours on folder setup. Because the scaffold can be customized through user‑defined conventions, Moarch adapts to existing style guides, naming conventions, or CI/CD requirements. It also supports both Riverpod and flutter_bloc, allowing teams to pick the state‑management library that aligns with their skill set or project constraints without rewriting the scaffold. For organizations that enforce FVM to lock Flutter SDK versions across developers, Moarch automatically creates the .fvm config, ensuring that everyone works with the same SDK version from the first commit.
From an architectural perspective, Moarch places the generated code squarely within the clean‑architecture paradigm. The `lib/src` directory is divided into `features`, `domain`, and `data` packages, each with clearly defined contracts and implementations. The `features` layer contains UI widgets and presentation logic, the `domain` layer holds use‑cases and entity definitions, and the `data` layer provides repository implementations and remote/local data sources. Dependency injection is wired using either Riverpod's ProviderScope or flutter_bloc's BlocProvider, giving developers a single source of truth for service location. This structure encourages testability: unit tests can target use‑cases in isolation, while integration tests can verify the end‑to‑end flow through the generated routes.
Getting started with Moarch is straightforward. After adding the package with the standard Flutter command, developers invoke the CLI to select the desired state manager, define the project name, and optionally point to a custom template folder. Moarch then runs `flutter create` under the hood, adds the appropriate dependencies, creates the FVM configuration, and writes a README that outlines the next steps. The generated README includes commands for running tests, launching the app, and updating the SDK version, which helps new contributors get up to speed quickly. For production‑grade projects, it is recommended to review the generated CI configuration, adjust lint rules to match the team's standards, and replace placeholder implementations with real data sources before committing.
While Moarch dramatically speeds up project bootstrapping, developers should be aware of a few production considerations. Because the scaffold is a starting point, the generated code contains placeholder services and mock data that must be replaced with secure, production‑ready implementations. Additionally, the CLI does not manage ongoing architectural changes; teams need to maintain the folder structure and dependency injection manually as the app evolves. Finally, Moarch is a development‑time tool only—it does not add runtime dependencies beyond the chosen state manager, so the final app size remains unaffected. By treating Moarch as a project‑initialization step rather than a library, teams can reap the benefits of rapid onboarding while retaining full control over long‑term architecture decisions.
Pros
- instant clean‑architecture scaffold
- supports both Riverpod and flutter_bloc
- automatic FVM setup
- customizable templates
- reduces onboarding time
Watch outs
- CLI only – no runtime library
- initial scaffold requires manual refinement for production
- limited to project initialization, not ongoing code generation
Setup notes
Run `flutter pub add moarch` to add the package. Then execute `dart pub global activate moarch` (or use the bundled binary) and run `moarch init` to start a new project. Follow the interactive prompts to choose Riverpod or flutter_bloc, set the project name, and optionally provide a custom template directory.
Requires Dart SDK >=2.19 and Flutter SDK >=3.10. Works on macOS, Linux, and Windows environments where the Flutter CLI is available. The generated project supports mobile, web, and desktop targets out of the box.
/// Example of the main.dart generated by Moarch when Riverpod is selected
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
final counterProvider = StateProvider<int>((ref) => 0);
void main() {
runApp(const ProviderScope(child: MyApp()));
}
class MyApp extends StatelessWidget {
const MyApp({Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Moarch Demo',
home: const CounterPage(),
);
}
}
class CounterPage extends ConsumerWidget {
const CounterPage({Key? key}) : super(key: key);
@override
Widget build(BuildContext context, WidgetRef ref) {
final count = ref.watch(counterProvider);
return Scaffold(
appBar: AppBar(title: const Text('Counter')),
body: Center(child: Text('Value: $count')),
floatingActionButton: FloatingActionButton(
onPressed: () => ref.read(counterProvider.notifier).state++,
child: const Icon(Icons.add),
),
);
}
}