home_sdk Free

Docs/Bricks/home_sdk

Tier

Freeversion 2.0.5

Command

archipelago generate home_sdk

Generates

• features/home/home_api
• features/home/home_impl

Generates first

auth_sdkwhen needed and missing, so there is nothing to install first

Depends on

flutter_l10ngenerate these first

Used by

introduction_sdk

Tutorial

Step-by-step: add home_sdk to a project

Home feature SDK with dashboard, profile, and settings pages using the dual-GetIt DI pattern and per-feature slang translations.

What it is

home_sdk generates the post-login landing feature: a dashboard (home), a profile page, and a settings page (including the language switcher), wired together behind a HomeShellPage and a HomeSDK contract other features can call to navigate there. Use it as the default post-auth destination in a generated app.

Variables

Variable	Type	Default	Description
appName	string	MyApp	The name of your application
prefix	string	App	Prefix for generated classes (e.g. App, My)
uiKitPackageName	string	app_ui_kit	Name of the UI kit package
isForMonorepo	boolean	true	Whether this will be part of a monorepo structure
stateManagement	enum	bloc	State management solution: bloc, cubit, riverpod, provider

stateManagement's default is bloc, not cubit, matching the parent flutter_modular_monorepo default (that brick has offered cubit too since 4.6.2, so every value here is reachable through archipelago create).

Usage

Interactive

archipelago generate home_sdk

Non-interactive (CI)

archipelago generate home_sdk --config my_config.json

Generated Structure

features/
└── home/
    ├── home_api/
    │   ├── lib/
    │   │   ├── home_api.dart
    │   │   └── src/
    │   │       └── home_sdk.dart                  # HomeSDK contract
    │   └── pubspec.yaml
    └── home_impl/
        ├── l10n/
        │   ├── en.i18n.json
        │   └── id.i18n.json
        ├── lib/
        │   ├── home_impl.dart
        │   └── src/
        │       ├── home_manifest.dart             # Routes + initial-path claim
        │       ├── home_sdk_impl.dart             # Lazy SDK
        │       ├── di/
        │       │   ├── home_global_module.dart    # Manifest + lazy SDK into the root
        │       │   ├── home_container.dart        # homeContainer (FeatureContainer)
        │       │   ├── home_imports.dart          # Root types home uses
        │       │   └── injector.dart
        │       ├── l10n/
        │       │   └── home_translations.g.dart   # Generated by slang
        │       ├── presentation/
        │       │   ├── home_shell_page.dart
        │       │   ├── home/home_page.dart
        │       │   ├── profile/
        │       │   │   ├── profile_page.dart
        │       │   │   └── cubit|bloc|notifiers/  # only the chosen stateManagement variant survives post_gen
        │       │   └── settings/settings_page.dart
        │       └── router/home_router.dart
        ├── slang.yaml
        ├── build.yaml
        ├── pubspec.yaml
        └── test/src/
            ├── di/home_di_test.dart                  # Lazy SDK, container isolation and teardown
            └── presentation/settings/settings_page_test.dart

Only the profile page has generated state-management variants (cubit/, bloc/, notifiers/ for riverpod and provider). home_page.dart and settings_page.dart are plain StatelessWidgets with no state-management branching. post_gen.dart deletes the profile sub-directories that don't match the chosen stateManagement value.

Public API

abstract interface class HomeSDK() {
  Future<void> launch(BuildContext context);             // same as goToHome
  Future<void> goToHome(BuildContext context);          // replaceAll to the home shell — no back stack
  Future<void> goToSection(BuildContext context, String sectionId); // 'profile' | 'settings', pushed
}

final homeSDK = getIt<HomeSDK>();
await homeSDK.goToHome(context);
await homeSDK.goToSection(context, 'profile');

DI and wiring

• Manifest + lazy SDK: HomeImplGlobalModule registers the const HomeManifest (routes and the priority-100 /home initial-path claim) with FeatureSDKRegistry, and HomeSDK as a lazy singleton. HomeSDKImpl is built the first time something resolves HomeSDK, not at boot. HomeSDK is a plain port and does not extend FeatureSDK. Home's local deps live in homeContainer, its own child GetIt: HomeShellPage takes a lease in initState and releases it in dispose, the first lease builds the container and the last release tears it down. The container resolves only what home registers plus the root types forwarded in home_imports.dart.
• post_gen.dart adds features/home/home_api and features/home/home_impl to the Dart workspace, adds a home_impl path dependency to the host app's pubspec.yaml, and registers HomeImplGlobalModule into the app's lib/di/injector.dart via ServiceLocatorUpdater — without this step the packages exist but the feature is never reached at runtime.
• The brick records itself as installed in archipelago.yaml via ArchipelagoConfigHelper.appendBrickInstalled('home_sdk').

Locale persistence

The Settings page's language tile is the reference implementation of the locale-persistence contract owned by flutter_l10n (>= 2.1.0). Any UI that changes the language must do both of these:

LocaleSettings.setLocale(HomeLocale.id);            // feature-scoped rebuild only
unawaited(
  app_l10n.AppLocaleController.setLocale(app_l10n.AppLocale.id), // app-wide + durable write
);

Never call app_l10n.LocaleSettings.setLocale(...) directly from UI — it looks applied but writes nothing, so the choice is lost on the next cold start. bootstrap.dart awaits AppLocaleController.restore() before runApp(), and HomeShellPage._syncLocale seeds HomeLocale from the restored app-wide locale on first build. test/src/presentation/settings/settings_page_test.dart covers the toggle → storage → cold-start-restore round trip.

Notifications tile

The Settings page's Notifications tile opens /notification-settings, the page push_notification_sdk (>= 1.3.1) registers. Home matches the path in FeatureSDKRegistry.instance.enabledPageConfigurations, so it has no dependency on the push packages. Without push the tile is hidden.

Dependencies on other bricks

• auth_sdk (hard, unconditional) — home_impl/pubspec.yaml declares auth_api: path: ../../auth/auth_api, and home_page.dart imports package:auth_api/auth_api.dart directly to call AuthSDK for the dashboard's logout button. pre_gen.dart self-generates auth_sdk via SubBrickGenerator when it is not already installed, passing through appName, prefix and uiKitPackageName.
• flutter_l10n — the app-wide locale controller/restore contract the Settings language tile writes through.
• The package named by the uiKitPackageName variable (default app_ui_kit) — design system extensions (context.colors, context.typography, context.spacing).

Limitations

• Always depends on auth_sdk (auto-generated if missing) — there is no standalone mode that omits the logout button / auth import.

Changelog

Run archipelago brick info home_sdk to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.