How to add a home dashboard with profile and settings to a Flutter app

Docs/Tutorials/home_sdk

Free Reference for home_sdk: every variable, option and package it generates. Command: archipelago generate home_sdk

Generate the Home SDK, understand its manifest, lazy SDK and feature container, pick a state management variant, and customize the pages.

What you'll learn

• Generating the Home SDK with dashboard, profile and settings pages
• Understanding the manifest, the lazy SDK and the feature container
• Choosing a state-management variant
• Customizing the pages and navigating to them

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

The brick needs auth_sdk because the dashboard logout button calls AuthSDK. The brick generates auth_sdk for you if it is missing. It also uses flutter_l10n for the locale and your UI kit for tokens.

Step 1: Generate the Home SDK

archipelago generate home_sdk

The prompts are:

• appName: your app name, for example MyApp
• prefix: the prefix for generated classes
• uiKitPackageName: the UI kit package. It is read from archipelago.yaml.
• isForMonorepo: leave this as true
• stateManagement: bloc (default), cubit, riverpod or provider

Or use a config file:

{
  "appName": "MyApp",
  "isForMonorepo": true,
  "stateManagement": "bloc"
}

archipelago generate home_sdk --config home_config.json

Step 2: Understand the Generated Structure

features/home/
├── home_api/
│   └── lib/src/home_sdk.dart          # HomeSDK contract
└── home_impl/
    ├── l10n/                          # en and id translations
    ├── lib/src/
    │   ├── home_manifest.dart         # Routes and the /home initial-path claim
    │   ├── home_sdk_impl.dart         # Lazy SDK
    │   ├── di/                        # Global module, container, imports
    │   ├── presentation/
    │   │   ├── home_shell_page.dart
    │   │   ├── home/home_page.dart
    │   │   ├── profile/               # Page and the chosen state-management variant
    │   │   └── settings/settings_page.dart
    │   └── router/home_router.dart
    └── test/src/
        ├── di/home_di_test.dart
        └── presentation/settings/settings_page_test.dart

Only the profile page has state-management variants. The hook deletes the variants you did not choose. The home and settings pages are plain widgets.

Step 3: Check the Registration

The post-generation hook adds the packages to the workspace and home_impl to the app pubspec.yaml. It registers HomeImplGlobalModule in lib/di/injector.dart. You write no registration code.

• The global module registers HomeManifest with FeatureSDKRegistry and HomeSDK as a lazy singleton. HomeSDKImpl is built when something first resolves HomeSDK.
• Home keeps its repositories and use cases in homeContainer, a child GetIt. HomeShellPage takes a lease in initState and releases it in dispose.
• home_imports.dart is the only file that reads the root. It forwards the types home needs.

Step 4: Navigate to Home

Other features call the port:

final homeSDK = getIt<HomeSDK>();
await homeSDK.goToHome(context);                 // replaceAll, no back stack
await homeSDK.goToSection(context, 'profile');   // 'profile' or 'settings', pushed

launch() is the same as goToHome(). The manifest claims the initial path /home with priority 100.

Step 5: Customize the Dashboard

Edit presentation/home/home_page.dart. Keep reading tokens from context.colors, context.typography and context.spacing:

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Padding(
        padding: EdgeInsets.all(context.spacing.md),
        child: Column(
          children: const [
            WelcomeHeader(),
            QuickActions(),
          ],
        ),
      ),
    );
  }
}

Step 6: Change the Language

The Settings page language tile is the reference for locale changes. It changes the feature locale for an immediate rebuild and the app-wide locale so it is saved:

LocaleSettings.setLocale(HomeLocale.id);
unawaited(app_l10n.AppLocaleController.setLocale(app_l10n.AppLocale.id));

See Setting Up Localization.

Step 7: Run the Tests

cd features/home/home_impl
flutter test

home_di_test.dart checks the lazy SDK, the container isolation and the teardown.

Common Customizations

Customization	Where to Change
Dashboard widgets	presentation/home/home_page.dart
Profile fields	presentation/profile/ and its state holder
Settings options	presentation/settings/settings_page.dart
Routes	router/home_router.dart and home_manifest.dart
Types home needs from the root	di/home_imports.dart

Bottom navigation that keeps every tab mounted (AutoTabsRouter.builder with an IndexedStack) needs a wrap. Wrap each tab in TickerMode(enabled: index == tabsRouter.activeIndex, ...). IndexedStack does not pause hidden tabs, so their animations keep running.

Next Steps

• Set up the UI Kit to theme your home pages
• Configure the Paywall for subscription-gated features