Getting Started

This page walks through setting up home_widget_generator, writing your first widget schema, generating native code, and using the generated Dart helper from your Flutter app.

• Add dependencies

  Add home_widget to your app's pubspec.yaml, and add home_widget_generator and home_widget_cli as dev dependencies:

  dependencies:
    home_widget: ^0.9.0
  
  dev_dependencies:
    home_widget_generator: ^0.0.1
    home_widget_cli: ^0.0.1
  

• Write a widget schema

  Create a Dart file describing your widget. By default home_widget_cli picks up files under a top-level home_widget/ folder. Here is a minimal schema:

  import 'package:home_widget_generator/home_widget_generator.dart';
  
  @HomeWidget(
    name: 'Basic Creation',
    android: HomeWidgetAndroidConfiguration(),
    iOS: HomeWidgetIOSConfiguration(
      groupId: 'group.com.example.app',
    ),
  )
  class BasicCreation {}
  

  The class itself stays empty - it only exists as an attachment point for the annotation. See the Annotation reference for every available parameter, and the Widgets section for the UI primitives you can pass via widget:.

• Add data and styling

  The widget: parameter accepts a tree of widgets. See the Widgets section for the available primitives, Data Types for binding values from home_widget storage, and Styling for colors, text styles and insets.

  import 'package:home_widget_generator/home_widget_generator.dart';
  
  @HomeWidget(
    name: 'Greeting',
    android: HomeWidgetAndroidConfiguration(),
    iOS: HomeWidgetIOSConfiguration(
      groupId: 'group.com.example.app',
    ),
    widget: HWColumn(
      crossAxisAlignment: HWCrossAxisAlignment.start,
      children: [
        HWText.fixed(
          'Hello',
          style: HWRoleTextStyle(role: HWTextStyleRole.caption),
        ),
        HWText(
          HWString('name', defaultValue: 'world'),
          style: HWRoleTextStyle(
            role: HWTextStyleRole.title,
            fontWeight: HWFontWeight.bold,
          ),
        ),
      ],
    ),
  )
  class Greeting {}
  

  Every HWString / HWInt / HWBool / HWDouble you reference inside widget: becomes a typed field on the generated helper, so you can update it without juggling string keys.

• Generate the code

  Run the CLI from your project root:

  dart run home_widget_cli generate
  

  The CLI scans for annotated classes and writes the generated Dart helper next to your other source under lib/src/home_widget/<name>.home_widget.dart, plus the iOS and Android widget sources into the corresponding native folders. See the generate command for all options.

• Use the generated Dart helper

  Import the generated file and call its static methods. For the schema above, the generator produces a GreetingHomeWidget class with the following static API:

  import 'src/home_widget/greeting.home_widget.dart';
  
  void main() {
    runApp(const MyApp());
  }
  
  Future<void> setName(String name) async {
    await GreetingHomeWidget.saveData(name: name);
    await GreetingHomeWidget.updateWidget();
  }
  

  • saveData(...) writes any of the declared data fields through home_widget in a type-safe way. Each field is an optional named parameter, so you can update one or many at a time.
  • getData() reads the current values back as a typed record.
  • deleteData(...) clears the given fields.
  • updateWidget() triggers a refresh of the native widget on both platforms, using the correct androidName / iOSName automatically.

  See Sync data for the underlying home_widget behavior.

• Native setup

  No manual native setup is needed: the CLI registers the widget receiver in AndroidManifest.xml, adds the iOS widget extension to the Xcode project, writes the entitlements file, and bumps the deployment target as required. You only need an App Group ID configured for iOS — provide it via the iOS: HomeWidgetIOSConfiguration(groupId: ...) field on the annotation.