Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

Getting Started

Creating Your First Project ​

What you'll learn ​

  • Scaffolding a new Flutter monorepo with Archipelago
  • Understanding the generated project structure
  • Running the generated app for the first time
  • Exploring the included developer tooling

Prerequisites ​

Step 1: Create the Project ​

Run the create command to scaffold a new monorepo. create is a shortcut for archipelago generate flutter_modular_monorepo:

bash
archipelago create --output ./my_app

The CLI writes a config template and opens it for you to fill in. It generates the project when you save and press Enter. The main options are:

  • appName: Used for package naming and display
  • organization and domain, Reverse domain parts, for example example and com
  • gitProvider: github or gitlab, decides which CI workflows are generated
  • stateManagement: bloc (default), cubit, provider or riverpod
  • networkLibrary, analyticsVendors, monitoringVendors, starterFeatures and more, see the flutter_modular_monorepo brick

The post-generation hook initializes git, runs melos bootstrap and the first code generation for you. Always pass --output so the project is not generated into an existing workspace.

archipelago createOne command, five steps, one project

Step 1 of 4, start: create prints the banner, then checks that your account may generate. Step 1 prepares the config. Step 2 loads the flutter_modular_monorepo brick, from the brick store by default.

archipelago create --output ./my_app   ▄█▄    archipelago  ▀▀▀▀▀   v2.7.0 ▄██ ██▄  Ship your Flutter app in days, not weeks. ██   ██  https://pub.dev/packages/archipelago_cliCreating new Archipelago project...[1/5] Preparing configuration...[2/5] Loading brick...✓ Loaded flutter_modular_monorepo brick

Step 2: Explore the Structure ​

The generated project follows a modular monorepo layout (the exact packages depend on your options):

text
my_app/
├── apps/
│   ├── my_app/              # Main Flutter app (orchestrator, with fastlane/)
│   └── my_app_widgetbook/   # Widgetbook UI catalog
├── features/                # Starter features: auth, home, introduction, paywall
├── infrastructure/          # network, analytics, monitoring, launch tracker, ...
├── shared/                  # app_config, feature_sdk, locale_core, router_registry, ...
├── packages/                # UI kit and assets
├── utilities/               # Lints and helpers
├── devtools/                # monorepo_toolkit and its script packages
├── .github/                 # CI/CD workflows (or .gitlab-ci.yml)
├── CLAUDE.md, AGENTS.md     # AI agent context files
├── build_prepare.yaml
├── flavors.yaml
└── pubspec.yaml             # Dart workspace root and melos scripts

Step 3: Run the App ​

Start a simulator or emulator, then use the toolkit's interactive runner from the project root:

bash
cd my_app
melos run run:app

It lets you pick the app, flavor and device. Or run Flutter directly:

bash
cd apps/my_app
flutter run --flavor development -t lib/main_development.dart

The host app reads every feature manifest through the two-phase initialization flow.

If melos run build fails on a fresh clone, make sure shared/app_config/.env exists: melos bootstrap seeds it from .env.development, or run melos run env:init followed by melos run env:switch -- development.

Step 4: Explore Developer Tooling ​

The devtools/ directory holds the monorepo_toolkit CLI. Every command is available as dart run monorepo_toolkit <command> and most as a melos script:

bash
# Validate the dependency graph against the architecture rules
melos run graph:validate

# Detect circular dependencies
melos run graph:cycles

# Swap debug tooling out for a production-flavor build (and back)
melos run build-prepare:production
melos run build-prepare:debug

# Pro: run tests with coverage; Enterprise: list affected packages
melos run coverage:full
melos run affected:list

See the Monorepo Toolkit guide for every command.

What's Included ​

Every generated project comes with:

  • GetIt dependency injection: Dual-GetIt pattern pre-configured
  • Router integration: Auto-registered feature routes
  • CI/CD templates: GitHub Actions workflows (or GitLab CI) ready to go
  • Fastlane configs: iOS and Android lanes in apps/my_app/fastlane/
  • AI agent context: CLAUDE.md, AGENTS.md, .cursorrules and Claude Code commands and skills
  • Linting rules: Strict analysis options across all packages

Next Steps ​

Learn how to add new features to your project in Generating Features.