Jade CLI

Jade is an interactive Dart CLI for creating Flutter apps with a reusable, layered project structure. It is designed for teams that want every new app to start with the same architecture, flavor setup, service boundaries, model conventions, shared widgets, tooling scripts, and agent-facing documentation.

Jade does not generate product-specific screens, branding, API URLs, or Firebase credentials. It generates a clean app foundation that can be reused across projects.

Requirements

  • Dart SDK compatible with ^3.3.1
  • Flutter SDK available on PATH

Jade calls flutter create during project creation, so Flutter must be installed and usable from the terminal.

Installation

dart pub global activate jade

Quick Start

jade create

The wizard asks for:

  • project name, folder name, description, and organization id
  • Flutter platforms: ios, android, web, macos, windows, linux
  • app flavors, defaulting to dev,production
  • optional Provider, GetIt, Hive, and Firebase setup

jade create is the only creation command. jade --create is intentionally rejected with usage guidance.

Other CLI commands:

jade create --verbose
jade --help
jade --version

What Jade Does

When you run jade create, Jade:

  1. Runs flutter create with the selected project metadata and platforms.
  2. Writes the Jade-style Flutter app structure into the new project.
  3. Generates flavor entrypoints and an app-local flavor configurator.
  4. Adds required dependencies with flutter pub add.
  5. Retries dependency installation with --offline if normal resolution fails.
  6. Adds selected optional scaffolding for Provider, GetIt, Hive, and Firebase.
  7. Runs the generated build executable with dart run <package>:build.
  8. Runs the flavor configurator for the selected platforms.
  9. Writes app-local docs/, rules/, AGENTS.md, and FLAVORS.md.

Flutter Architecture Pattern

Jade apps follow a simple downward flow. In Provider-enabled apps, the core feature path is:

ui -> state (providers) -> services

That is the main rule: screens and widgets call providers, providers coordinate services, and services return typed models or simple results.

The goal is to keep responsibilities obvious:

  • constants contains app-wide configuration, route names, asset paths, and fixed values.
  • extensions contains small framework and value helpers.
  • models contains typed data shapes. Generated models extend BaseModel, BaseModel extends Equatable, and JSON serialization uses json_serializable.
  • services contains API, Firebase, Hive, storage, and platform integration work.
  • providers is generated only when Provider is enabled. Providers coordinate services and expose domain state, but they should not own generic loading methods or generic loading variables.
  • theme contains app colors and ThemeData.
  • ui contains route destinations and feature screens.
  • utils contains cross-cutting helpers such as validation, routes, spacing, and request helpers.
  • widgets contains reusable UI components grouped by role.

Screens should stay thin. Widgets compose UI. Services perform IO and platform work. Models keep transport and persistence data typed.

Generated Project Structure

Jade writes a complete starter app, but the structure is easier to understand by role than by memorizing every file.

Area Purpose
lib/constants App configuration, generated asset constants, route names, and fixed values.
lib/extensions Small framework and value helpers.
lib/models Base models, API response models, pagination models, flavor config models, and remote config models.
lib/services API and service-location code, plus optional Hive and Firebase services.
lib/providers Optional Provider scaffolding when Provider is selected.
lib/theme App colors and ThemeData.
lib/ui Route destinations and feature screens.
lib/utils Validation, routing, spacing, and cross-cutting helpers.
lib/widgets Reusable UI grouped under feedback, forms, indicators, and layout.
bin Generated Dart maintenance executables: build.dart and watch.dart.
tool App-local automation, including configure_flavors.dart.
docs and rules Generated Markdown documentation for humans and coding agents. 
<project-folder>/
  assets/
    fonts/
    images/
  bin/
    build.dart
    watch.dart
  lib/
    constants/
    extensions/
    models/
    providers/       # populated when Provider is enabled
    services/
    theme/
    ui/
    utils/
    widgets/
      feedback/
      forms/
      indicators/
      layout/
  tool/
    configure_flavors.dart
  docs/
  rules/
  AGENTS.md
  FLAVORS.md
  preflight.sh
  <project-folder>.sh

Jade also writes app-level barrels such as models.dart, theme.dart, utils.dart, widgets.dart, and extensions.dart, plus lib/flavors.dart, lib/main.dart, and one lib/main_<flavor>.dart entrypoint per flavor.

Optional files are factual to the wizard choices:

  • Provider adds lib/providers/base_provider.dart, lib/providers/app_provider.dart, and lib/providers/user_provider.dart.
  • Hive adds lib/services/hive_service.dart.
  • Firebase adds lib/services/firebase_service.dart.

Flavors

Flavor names must be lower-camel-case alphanumeric identifiers that start with a lowercase letter. The default flavors are:

dev,production

Jade generates one entrypoint per flavor:

lib/main_dev.dart
lib/main_production.dart

Run a flavor with Flutter's normal flavor flags:

flutter run --flavor dev --target lib/main_dev.dart

After changing flavors or selected platforms, rerun:

dart run tool/configure_flavors.dart --flavors=dev,production --platforms=ios,android --app-name="My App" --package-name=my_app

The configurator updates .vscode/launch.json, Android flavor blocks when Android is selected, iOS/macOS xcconfig files when those platforms are selected, and FLAVORS.md.

Generated Tooling

Generated apps include two Dart executables:

  • bin/build.dart runs build_runner build, refreshes lib/models.dart, refreshes lib/constants/app_assets.dart, and formats the project.
  • bin/watch.dart starts build_runner watch, watches lib/models, watches assets, and keeps generated barrels current.

Run them through the package executable names:

dart run <package>:build
dart run <package>:watch

Generated apps also include:

  • <project-folder>.sh for flavor-aware Android and iOS run/build commands
  • preflight.sh for release-readiness checks
  • tool/configure_flavors.dart for flavor wiring

Use bin/watch.dart, not watch.dat.

Dependencies Added To Generated Apps

Jade always adds:

  • intl
  • recase
  • equatable
  • json_annotation
  • path
  • dio
  • cached_network_image
  • package_info_plus

Jade always adds these dev dependencies:

  • build_runner
  • json_serializable

Optional selections add:

  • Provider: provider
  • GetIt: get_it
  • Hive: hive, encrypt:5.0.1, path_provider
  • Firebase: firebase_core, firebase_analytics, firebase_crashlytics, firebase_messaging, firebase_remote_config

Firebase

When Firebase setup is selected, Jade generates lib/services/firebase_service.dart with Firebase Core, Analytics, Crashlytics, Messaging, and Remote Config hooks.

Jade does not generate Firebase credentials. Run flutterfire configure in the generated app and pass the generated options to FirebaseService.initialize when the Firebase project is ready.

Generated Documentation

Every generated app includes local Markdown documentation:

  • AGENTS.md gives coding agents the working contract, feature flow, do/don't rules, generated-file ownership notes, and finishing checklist.
  • docs/architecture.md explains the generated app layers.
  • docs/flavors.md explains flavor entrypoints and configurator usage.
  • docs/services.md explains generated services and optional state/storage choices.
  • docs/tooling.md explains generated executable and maintenance scripts.
  • rules/architecture.md records layer placement rules.
  • rules/bin-and-tools.md records executable and tooling rules.
  • rules/services-providers.md records service/provider boundaries.
  • FLAVORS.md lists generated flavors and run commands.

These files are generated per app and reflect the options selected in the wizard.

Developing Jade

dart pub get
dart format bin lib test
dart analyze
dart test
dart doc --dry-run

Run the opt-in smoke test when Flutter is available:

JADE_RUN_SMOKE_TESTS=1 dart test test/generated_app_smoke_test.dart

The smoke test creates a temporary Flutter app, runs Jade's generator, runs the generated build executable, and analyzes the generated app.

Jade's public Dart API documentation is configured by dartdoc_options.yaml and exposed through lib/jade.dart.

License

This project is licensed under the terms of the LICENSE file.

Libraries

jade
Testable building blocks for the Jade Flutter project generator.