clarc

clarc is a command-line tool for scaffolding Flutter projects with a Clean Architecture structure. The package is published as clarc_arch_cli, while the executable command remains clarc.

Features

  • Create a new Flutter project with a Clean Architecture structure.
  • Add common dependencies: Dio, Dartz, Flutter Bloc, Get It, GoRouter, Equatable, Freezed, JSON Serializable, Shared Preferences, and Pretty Dio Logger.
  • Generate complete feature modules from the data, domain, and presentation layers.
  • Generate the default home feature as a complete module, not just a page.
  • Generate pages inside an existing module and register them in GoRouter.
  • Register module dependencies in Get It.
  • Generate API endpoint constants in core/constants/api_endpoints.dart.
  • Use Either<Failure, T> for generated repository, use case, and Bloc flows.
  • Generate reusable app colors, text styles, and light/dark themes.
  • Add a light/dark mode toggle to the default project home page.
  • Support multiple Flutter runners:
    • flutter
    • fvm flutter
    • puro flutter
  • Choose the runner through an interactive wizard or the --flutter-cmd flag.
  • Optionally scaffold a local database setup with sqflite.

Install

After the package is available on pub.dev:

dart pub global activate clarc_arch_cli

Then run:

clarc --help

Make sure the Dart global pub executables directory is available in your PATH.

Local Install

dart pub get
dart pub global activate --source path .

After activation, run:

clarc --help

During development, you can also run the executable directly:

dart run clarc_arch_cli:clarc --help

Interactive Wizard

The easiest way to start is to run the command without full arguments:

clarc create project

The CLI will ask:

What project do you want to create?
Which Flutter runner do you want to use?
  1. Flutter (default)
  2. FVM
  3. Puro
  4. Auto detect
  5. Custom command
Does this project use a local sqflite database?

For modules and pages:

clarc create module
clarc create page

The CLI will ask for the module or page name if it is not provided.

Flutter Runner

The wizard uses Flutter as the first and default option. This is best for users who run Flutter directly from PATH.

Runner options:

  • Flutter runs flutter ....
  • FVM runs fvm flutter ....
  • Puro runs puro flutter ....
  • Auto detect reads the Flutter manager configuration from the project folder.

Auto detect resolves the runner like this:

  • If .fvmrc or .fvm exists, use fvm flutter.
  • If .puro.json or .puro exists, use puro flutter.
  • Otherwise, use flutter.

Manual override:

clarc create project my_app --flutter-cmd flutter
clarc create project my_app --flutter-cmd "fvm flutter"
clarc create project my_app --flutter-cmd "puro flutter"

When using FVM or Puro, the Flutter version is controlled by that tool. clarc does not lock or override the Flutter version.

Create A Project

clarc create project my_app --org com.example

If the project name is not provided, the CLI will ask for it.

Generated projects include:

  • A custom main.dart that initializes Get It before running the app.
  • A router setup in lib/app/router/app_router.dart.
  • App theme files in lib/core/theme.
  • A default home feature with Clean Architecture layers.
  • A default home page with a light/dark mode toggle.
  • A Clarc-aware widget test that pumps App instead of Flutter's default MyApp.

To scaffold local database support:

clarc create project my_app --local-db
clarc create project my_app --no-local-db

Useful options:

clarc create project my_app --path ./apps
clarc create project my_app --platforms android,ios,web
clarc create project my_app --skip-flutter-create
clarc create project my_app --no-pub-get
clarc create project my_app --force
clarc create project my_app --yes

clarc asks for confirmation before larger actions such as running flutter create, using a non-empty folder, or running pub get. If you generate into an existing project folder, existing generated files are skipped by default. Use --force only when you want to overwrite generated files such as lib/app/app.dart or lib/features/home/presentation/pages/home_page.dart.

Create A Module

clarc create module auth --project-dir ./my_app

Generated module structure:

lib/features/auth/
  data/
    datasources/
    models/
    repositories/
  domain/
    entities/
    repositories/
    usecases/
  presentation/
    bloc/
    pages/

Entity files use the *_clarc.dart naming convention, for example:

lib/features/auth/domain/entities/auth_clarc.dart

In addition to writing files, clarc also:

  • Registers the default module route in lib/app/router/app_router.dart.
  • Registers the Bloc, UseCase, Repository, and DataSource in lib/core/di/injection.dart.
  • Offers to run build_runner.

Example with FVM:

clarc create module auth --project-dir ./my_app --flutter-cmd "fvm flutter"

Create A Page

clarc create page auth login --project-dir ./my_app

This creates:

lib/features/auth/presentation/pages/login_page.dart

Then it registers the route:

/auth/login

If the module does not exist, the CLI asks whether it should create the module first.

Generated Project Structure

A new project gets this base structure:

lib/
  app/
    app.dart
    theme_controller.dart
    router/
      app_router.dart
  core/
    constants/
      api_endpoints.dart
    database/
      app_database.dart
    di/
      injection.dart
    error/
      failure.dart
    network/
      api_client.dart
    theme/
      app_colors.dart
      app_text_styles.dart
      app_theme.dart
    usecases/
      usecase.dart
  features/
    home/
      data/
        datasources/
        models/
        repositories/
      domain/
        entities/
        repositories/
        usecases/
      presentation/
        bloc/
        pages/
  main.dart

The core/database folder is created only when local database support is enabled. The default home page includes the project-level theme toggle. Pages generated later with clarc create module or clarc create page stay simple and do not include theme toggle logic.

clarc create project my_app --org com.example
cd my_app
clarc create module auth
clarc create page auth login

With FVM:

fvm use 3.24.0
clarc create project my_app --flutter-cmd "fvm flutter"
cd my_app
clarc create module auth --flutter-cmd "fvm flutter"

Development

dart format bin lib test
dart analyze
dart test

Publish

Before publishing a new version:

dart format bin lib test
dart analyze
dart test
dart pub publish --dry-run

If the dry run passes, publish with:

dart pub publish

Published versions cannot be replaced. Always bump version in pubspec.yaml and add a matching entry in CHANGELOG.md before publishing.

Libraries

clarc
clarc_cli