playbooks

home / skills / willsigmon / sigstack / widget-extension-builder

widget-extension-builder skill

/plugins/ios-dev/skills/widget-extension-builder

This skill helps you create and refresh iOS widgets for Leavn by managing data sharing, localization, and refresh strategies.

npx playbooks add skill willsigmon/sigstack --skill widget-extension-builder

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
773 B
---
name: Widget Extension Builder
description: Create and maintain iOS widgets for Leavn - VOTD widget, reading plan widget, prayer widget with proper data sharing and refresh
allowed-tools: Read, Write, Edit
---

# Widget Extension Builder

Build iOS widgets:

1. **Widget types**:
   - VerseOfDayWidget
   - ReadingPlanWidget
   - CommunityPrayerWidget
   - ReadingLiveActivity

2. **Data sharing**:
   - Use SharedWidgetStore
   - App group: `group.com.leavn.app`
   - Write from main app, read from widget

3. **Localization**:
   - Use WidgetI18n (separate from main app)
   - All 6 languages supported

4. **Refresh**:
   - Timeline provider
   - Background refresh
   - User-triggered reload

Use when: Creating widgets, updating widget data, widget refresh issues

Overview

This skill builds and maintains iOS widgets for the Leavn app family, including Verse of the Day, Reading Plan, Community Prayer widgets, and a Reading LiveActivity. It provides patterns for safe data sharing via an app group, localized widget strings, and strategies for reliable refresh behavior. The skill focuses on practical integration between the main app and widget extensions using TypeScript-driven tooling and configuration.

How this skill works

The skill configures widget extensions to read data from a SharedWidgetStore backed by the app group group.com.leavn.app so the main app can write updates and widgets can read them. It supplies a timeline provider with background refresh and user-triggered reload hooks, plus a separate WidgetI18n resource to load localized strings for six supported languages. LiveActivity support is included for reading sessions, with explicit refresh and expiration handling.

When to use it

  • Adding a new iOS widget (VOTD, Reading Plan, Prayer) to the Leavn app.
  • Implementing LiveActivity for ongoing reading sessions.
  • Sharing data between the main app and widget extensions using an app group.
  • Troubleshooting widget refresh timing or background updates.
  • Localizing widget text independently of the main app.

Best practices

  • Write all widget-updating data from the main app into SharedWidgetStore under group.com.leavn.app to avoid permission and sandbox issues.
  • Keep WidgetI18n separate from the app localization bundle so widget strings remain stable across releases.
  • Use the timeline provider for scheduled content and implement background refresh handlers with conservative intervals to preserve battery.
  • Expose a user-triggered reload endpoint from the app to let users force an immediate widget refresh when content changes.
  • Test LiveActivity lifecycle: start, update, and end flows with explicit expiration to prevent stale displays.

Example use cases

  • Presenting daily scripture in a VerseOfDayWidget with localized titles and tapping to open the app.
  • Displaying the current reading step and progress in a ReadingPlanWidget synced from the main app.
  • Showing active prayer requests in CommunityPrayerWidget that refresh when new requests are posted.
  • Running a ReadingLiveActivity during a timed reading session with periodic updates from the app.
  • Fixing an issue where widgets show outdated content by ensuring the app writes timely updates to SharedWidgetStore.

FAQ

How does the widget read data from the main app?

Widgets read from SharedWidgetStore using the app group group.com.leavn.app; the main app must write updates into that store.

Where should localization live for widgets?

Use a separate WidgetI18n resource for widget strings so you can manage six supported languages independently of the main app.