home_widget Pro

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

Version: 1.0.0

Variables

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

Generated Packages

Package	Purpose
home_widget_api	HomeWidgetSDK abstract interface + WidgetData / WidgetTapEvent models
home_widget_impl	Plugin wrapper with Android AppWidgetProvider + iOS WidgetKit reference code

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/
    │       └── models/
    └── home_widget_impl/
        ├── android/src/main/
        │   ├── kotlin/com/archipelago/home_widget_impl/
        │   └── res/
        │       ├── layout/          # sample_app_widget.xml
        │       └── xml/             # sample_app_widget_info.xml
        ├── ios/Classes/
        │   └── HomeWidgetExtensionResources/
        │       └── SampleWidget.swift
        └── lib/src/
            └── di/

Android Setup

The post-gen hook wires both packages into the workspace. Additionally, add the receiver to android/app/src/main/AndroidManifest.xml:

<receiver android:name=".SampleAppWidgetProvider" android:exported="true">
  <intent-filter>
    <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
  </intent-filter>
  <meta-data
    android:name="android.appwidget.provider"
    android:resource="@xml/sample_app_widget_info" />
</receiver>

Copy the generated res/layout/ and res/xml/ files into your host app's res/ directory.

iOS Setup (Manual — Xcode Required)

The brick cannot mutate .xcodeproj files. These steps must be done in Xcode:

1. Create Widget Extension target — File > New > Target > Widget Extension. Uncheck "Include Configuration Intent".
2. Copy SampleWidget.swift — from the generated ios/Classes/HomeWidgetExtensionResources/ into your new target's source folder.
3. Enable App Groups (main app target) — Signing & Capabilities > + Capability > App Groups. Add group.com.example.app.
4. Enable App Groups (widget extension target) — repeat with the same group ID.
5. Call setAppGroupId in Flutter before any widget read/write call:

   await HomeWidget.setAppGroupId('group.com.example.app');

6. Add WidgetKit.framework — Widget Extension target > Build Phases > Link Binary With Libraries.

Runtime API

// 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 cold-start widget tap
final initialTap = await getIt<HomeWidgetSDK>().getInitialTapEvent();
if (initialTap != null) {
  router.push(initialTap.action);
}

Data Flow (iOS)

Flutter (HomeWidgetSDKImpl.updateWidget)
  → home_widget plugin saves to UserDefaults(suiteName: appGroupId)
  → WidgetCenter.reloadAllTimelines()
    → SampleProvider.getTimeline() reads UserDefaults
      → widget re-renders with new data