📱 Home Widget Command

Overview

The widget command generates native home screen widgets for both iOS and Android platforms. From a simple JSON configuration file, it scaffolds all necessary code and files to integrate home screen widgets into your Flutter application.

Command

apparence_cli widget [path] 

This command:

• Generates native iOS widgets (Swift/SwiftUI) and Android widgets (Kotlin/Compose)
• Creates Flutter service classes for widget data management
• Sets up background updates using WorkManager
• Configures App Groups for iOS
• Automatically integrates with your app's main initialization

Options

Option	Alias	Description	Default
--force	-f	Force home widgets generation even if already exists	false

Prerequisites

1. Create Configuration File

Before running the command, create a home_widget_config.json file in your project root:

{
  "widgets": [
    {
      "name": "MyWidget",
      "description": "A sample home widget",
      "metadata": {
        "title": {
          "type": "string",
          "defaultValue": "Hello"
        },
        "counter": {
          "type": "number",
          "defaultValue": "0"
        }
      },
      "isLockScreenWidget": false,
      "iosSizes": ["systemSmall", "systemMedium", "systemLarge"],
      "androidSize": {
        "minWidth": 180,
        "minHeight": 180,
        "targetCellWidth": 2,
        "targetCellHeight": 2
      }
    }
  ]
}

You can define multiple widgets in the widgets array. Make sure to name them uniquely.

2. Platform Requirements

• iOS: Xcode project at ios/ directory
• Android: Android project at android/ directory
• At least one platform must be present

To generate an iOS widget you must be on a macOS system with Xcode installed.

Configuration Schema

Widget Configuration

Field	Type	Required	Description
name	string	✅	Widget identifier (PascalCase recommended)
description	string	✅	Widget description shown to users
metadata	object	✅	Data fields that can be sent to the widget
isLockScreenWidget	boolean	❌	Enable lock screen support (iOS only)
iosSizes	array	❌	Supported iOS widget sizes
androidSize	object	❌	Android widget dimensions

iOS Widget Sizes

Available values for iosSizes:

• systemSmall - Small widget (2x2 grid)
• systemMedium - Medium widget (4x2 grid)
• systemLarge - Large widget (4x4 grid)
• accessoryCircular - Circular lock screen widget
• accessoryRectangular - Rectangular lock screen widget
• accessoryInline - Inline lock screen widget

Android Widget Size

Field	Type	Required	Description
minWidth	number	✅	Minimum width in dp
minHeight	number	✅	Minimum height in dp
targetCellWidth	number	❌	Target grid cells horizontally
targetCellHeight	number	❌	Target grid cells vertically
maxResizeWidth	number	❌	Maximum resize width in dp
maxResizeHeight	number	❌	Maximum resize height in dp
resizeMode	string	❌	Resize options: "none", "horizontal", "vertical", "horizontal|vertical"

Metadata Types

Type	Description	Example Default Value
string	Text data	"Hello World"
number	Numeric data	"42"
boolean	Boolean data	"true" or "false"
datetime	Date/time data	ISO 8601 string

What Gets Generated

Flutter Files

lib/
└── core/
    └── home_widgets/
        ├── home_widget_service.dart           # Main service provider
        ├── home_widget_mywidget_service.dart  # Widget-specific service
        └── home_widget_manager.dart           # Background update manager

iOS Files (Swift/SwiftUI)

ios/
└── HomeWidgetExtension/
    ├── MyWidget.swift          # Widget UI code
    ├── Info.plist             # Extension configuration
    └── Assets.xcassets        # Widget assets

Android Files (Kotlin/Compose)

android/app/src/main/
├── kotlin/[package]/
│   └── MyWidget.kt            # Widget UI code (Compose)
└── res/
    ├── xml/
    │   └── mywidget_info.xml  # Widget configuration
    └── layout/
        └── mywidget.xml       # Widget layout

Automatic Integration

The command automatically:

1. ✅ Installs dependencies: home_widget, background_fetch
2. ✅ Updates main.dart to include homeWidgetsManagerProvider
3. ✅ Configures App Groups for iOS
4. ✅ Runs code generation (build_runner)
5. ✅ Formats and fixes generated code

Post-Generation Steps

iOS Setup

1. Open ios/Runner.xcworkspace in Xcode
2. Verify App Groups capability is configured
3. Ensure the extension target is properly configured
4. Build and run the app

Android Setup

1. Build and run your app
2. Add the widget to your home screen from the widget picker

Customization

iOS Widget Code: Edit ios/HomeWidgetExtension/[WidgetName].swift

Android Widget Code: Edit android/app/src/main/kotlin/[packageName]/[WidgetName].kt

Flutter Integration: Use lib/core/home_widgets/home_widget_service.dart to send data to widgets

Sending Data to Widgets

To update your widget from Flutter manually call :

await ref.read(myWidgetHomeWidgetProvider).update();

Customize the update logic

open the file lib/core/home_widgets/home_widget_[YOUR_WIDGET_NAME].dart and modify the method update By default it looks like this :

@override
Future<void> update() {
  Logger().i('🔄 Updating [YOUR_WIDGET_NAME] Home Widget');
  // Example: fetch some data from the user state
  final userState = ref.read(userStateNotifierProvider);
  final userName = userState.user.idOrNull ?? 'Guest';

  return updateWidget({
    ... // all widget properties or null
  });
}

As this method has access to the riverpod ref, you can read any provider to get the data you want to display in the widget.

Background Updates

The command configures background task to update widgets automatically every 15 minutes. Customize this behavior in home_widget_manager.dart.

Background updates on iOS may be limited by system policies. You can't guarantee exact timing and cannot set it to less than 15 minutes.

Dependencies Installed

• home_widget - Platform communication
• background_fetch - Background execution

Platform Guidelines

• iOS: Apple Widget Design Guidelines
• Android: Android App Widgets Layout

Troubleshooting

Widget doesn't appear

• Ensure the app has been built and installed at least once
• Check Xcode console (iOS) or logcat (Android) for errors
• Verify App Groups are configured correctly (iOS)

Data not updating

• Check that homeWidgetsManagerProvider is added to Initializer
• Verify background permissions are granted
• Check WorkManager logs for background task execution

Build errors

• Run flutter clean and rebuild
• Ensure all native dependencies are installed
• Check that bundle ID matches configuration (iOS)

License Limits

This feature may be subject to license limits. Check your license plan for the widget feature limit.

---

Plugin Documentation: home_widget on pub.dev