home_widget Pro

Docs/Bricks/home_widget

Tier

Proversion 1.2.7

Command

archipelago generate home_widget

Generates

• features/home_widget/home_widget_api
• features/home_widget/home_widget_impl

Depends on

shared_identifiersgenerate these first

Tutorial

Step-by-step: add home_widget to a project

Home screen widget scaffold. Wraps the home_widget Flutter plugin (^0.10.0) with a clean HomeWidgetSDK contract, an injectable implementation, and reference native scaffolding for iOS WidgetKit and Android AppWidget.

Variables

Variable	Type	Default	Description
appGroupId	string	(no default — prompted)	iOS App Group identifier (e.g. group.com.example.app). Must be registered in the Apple Developer console and enabled as an Xcode capability on both the main app target and the widget extension target.

Usage

Interactive

archipelago generate home_widget

Non-interactive (CI)

archipelago generate home_widget --config my_config.json

Generated Structure

features/
└── home_widget/
    ├── home_widget_api/
    │   └── lib/src/
    │       ├── home_widget_sdk.dart          # HomeWidgetSDK contract
    │       └── models/
    │           ├── widget_data.dart          # WidgetData
    │           └── widget_tap_event.dart     # WidgetTapEvent
    └── home_widget_impl/
        ├── android/src/main/
        │   ├── AndroidManifest.xml           # declares the widget receiver
        │   ├── kotlin/com/archipelago/home_widget_impl/
        │   │   ├── HomeWidgetImplPlugin.kt
        │   │   └── SampleAppWidgetProvider.kt
        │   └── res/
        │       ├── layout/sample_app_widget.xml
        │       └── xml/sample_app_widget_info.xml
        ├── ios/Classes/HomeWidgetExtensionResources/
        │   ├── Info.plist
        │   └── SampleWidget.swift
        └── lib/src/
            ├── home_widget_sdk_impl.dart
            └── di/

API

abstract interface class HomeWidgetSDK implements FeatureSDK {
  bool get isSupported;   // true on Android/iOS, false on web/desktop
  Future<void> updateWidget(WidgetData data);
  Stream<WidgetTapEvent> get tapStream;
  Future<WidgetData?> getCurrentData();
  Future<WidgetTapEvent?> getInitialTapEvent();
}

class WidgetData {
  const WidgetData({required this.values});   // Map<String, Object> — String/int/double/bool only
  const WidgetData.empty();
}

class WidgetTapEvent {
  const WidgetTapEvent({required this.uri, required this.widgetId, required this.action, this.payload = const {}});
  factory WidgetTapEvent.fromUri(Uri uri);   // widgetId <- uri.scheme, action <- uri.host, payload <- uri.queryParameters
}

// Push data to the widget
await getIt<HomeWidgetSDK>().updateWidget(
  const WidgetData(values: {'title': 'Hello from Flutter'}),
);

// Subscribe to widget taps (while app is running)
getIt<HomeWidgetSDK>().tapStream.listen((event) {
  // event.action, event.payload, event.widgetId
});

// Handle a cold-start widget tap
final initialTap = await getIt<HomeWidgetSDK>().getInitialTapEvent();
if (initialTap != null) {
  router.push(initialTap.action);
}

HomeWidgetSDKImpl self-registers with FeatureSDKRegistry on construction. updateWidget type-dispatches each values entry to HomeWidget.saveWidgetData<T> (String/int/double/bool only — anything else throws ArgumentError), then calls HomeWidget.updateWidget(name:, androidName:, iOSName:) to trigger the native re-render; any failure (native PlatformException or the ArgumentError) is caught, logged, and swallowed — updateWidget never throws to the caller. getCurrentData() only reads the 'title' key as a reference implementation — extend it to read every key your widget layout actually uses.

Dependency injection

# home_widget_impl/pubspec.yaml
archipelago:
  di_modules:
    - class: HomeWidgetImplPackageModule

post_gen.dart adds both packages to the workspace, adds home_widget_api/home_widget_impl to the app's pubspec.yaml, and wires HomeWidgetImplPackageModule into the app's injector.dart.

Platform Setup

Android

No manual steps. home_widget_impl is a Flutter plugin for Android. Its own android/src/main/AndroidManifest.xml declares SampleAppWidgetProvider, and its res/ holds the layout and widget metadata. Gradle merges both into the app, so you add nothing to the app's manifest or res/. The Dart side updates the widget by its fully qualified class name, com.archipelago.home_widget_impl.SampleAppWidgetProvider.

iOS (manual — Xcode required)

The brick cannot mutate .xcodeproj files, so post_gen.dart only prints these steps; nothing below is applied automatically:

1. Create a Widget Extension target — File > New > Target > Widget Extension. Uncheck "Include Configuration Intent".
2. Copy SampleWidget.swift from the generated ios/Classes/HomeWidgetExtensionResources/ into the new target's source folder.
3. Enable App Groups on both the main app target and the widget extension target — Signing & Capabilities > + Capability > App Groups, using the appGroupId you configured.
4. Add WidgetKit.framework to the Widget Extension target's Build Phases > Link Binary With Libraries.

HomeWidget.setAppGroupId('<appGroupId>') is called for you: HomeWidgetSDKImpl runs it once on construction and every updateWidget/getCurrentData/getInitialTapEvent awaits it first (since 1.2.0). Only the Xcode-side App Group capability stays manual.

Dependencies

• feature_sdk, router_registry, identifiers (shared workspace packages)
• home_widget: ^0.10.0

Known Limitations

• getCurrentData() only reads the 'title' key; extend it yourself for a real widget's full data set.
• The brick scaffolds one sample widget provider, not a production widget UI.
• The brick cannot touch .xcodeproj — every iOS step is manual.

Changelog

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