react-native-live-widgets 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +197 -49
  3. package/android/build.gradle +14 -20
  4. package/android/src/main/AndroidManifest.xml +1 -0
  5. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +2 -1
  6. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +8 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +4 -1
  8. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +29 -3
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +21 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +51 -15
  11. package/android/src/main/res/layout/rn_live_widget_host.xml +64 -74
  12. package/app.plugin.js +114 -0
  13. package/assets/cross_platform_parity.png +0 -0
  14. package/assets/donate_qr.png +0 -0
  15. package/assets/dynamic_island_expanded.png +0 -0
  16. package/assets/home_widget_interactive.png +0 -0
  17. package/assets/lock_screen_live_activity.png +0 -0
  18. package/cli/setup.js +445 -48
  19. package/docs/EXPO-GUIDE-EN.md +405 -0
  20. package/docs/EXPO-GUIDE-VI.md +427 -0
  21. package/docs/GUIDE-EN.md +75 -14
  22. package/docs/GUIDE-VI.md +75 -14
  23. package/docs/index.html +405 -0
  24. package/docs/llms-full.txt +118 -0
  25. package/docs/llms.txt +66 -0
  26. package/lib/builder.js +9 -13
  27. package/lib/builder.js.map +1 -1
  28. package/lib/dispatcher.js +6 -11
  29. package/lib/dispatcher.js.map +1 -1
  30. package/lib/index.d.ts.map +1 -1
  31. package/lib/index.js +40 -53
  32. package/lib/index.js.map +1 -1
  33. package/lib/types.js +1 -2
  34. package/lib/types.js.map +1 -1
  35. package/package.json +22 -4
  36. package/src/index.ts +12 -4
  37. package/src/react-native-env.d.ts +29 -0
@@ -0,0 +1,405 @@
1
+ # EXPO INTEGRATION & USAGE GUIDE FOR REACT-NATIVE-LIVE-WIDGETS 🚀
2
+
3
+ > 🌐 **Language:** **English** • [🇻🇳 Hướng dẫn Tiếng Việt (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md) • [📖 Bare RN Guide (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Expo Live Demo Repository](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
4
+
5
+ This guide provides a comprehensive walkthrough for integrating **`react-native-live-widgets`** into **Expo (SDK 50, 51, 52, 58+)** projects — covering Expo Config Plugins, automatic iOS WidgetKit/ActivityKit configuration, local testing via Expo Dev Client, and production cloud builds with **EAS Build**.
6
+
7
+ ---
8
+
9
+ ## TABLE OF CONTENTS
10
+ 1. [Understanding Expo & Native Widgets Architecture](#1-understanding-expo--native-widgets-architecture)
11
+ 2. [Official Expo Demo Repository (LiveWidgetsExampleExpo)](#2-official-expo-demo-repository-livewidgetsexampleexpo)
12
+ 3. [Step-by-Step Installation & Setup](#3-step-by-step-installation--setup)
13
+ - [Step 1: Install Package](#step-1-install-package)
14
+ - [Step 2: Configure app.json (Expo Config Plugin)](#step-2-configure-appjson-expo-config-plugin)
15
+ - [Step 3: Run Expo Prebuild](#step-3-run-expo-prebuild)
16
+ - [Step 4: Run CLI Wizard for Widget Extension](#step-4-run-cli-wizard-for-widget-extension)
17
+ 4. [Running & Testing on Simulators & Devices](#4-running--testing-on-simulators--devices)
18
+ - [Run on iOS Simulator](#run-on-ios-simulator)
19
+ - [Run on Android Emulator](#run-on-android-emulator)
20
+ - [Adding Home Widgets and Live Activities on Simulator](#adding-home-widgets-and-live-activities-on-simulator)
21
+ 5. [EAS Build Configuration (Expo Application Services)](#5-eas-build-configuration-expo-application-services)
22
+ - [Register App Groups & Extension on Apple Developer](#register-app-groups--extension-on-apple-developer)
23
+ - [Configure eas.json](#configure-easjson)
24
+ - [Provisioning Profiles for Extension](#provisioning-profiles-for-extension)
25
+ 6. [TypeScript Example for Expo (Widgets & Live Activity)](#6-typescript-example-for-expo-widgets--live-activity)
26
+ 7. [Troubleshooting Common Expo Issues](#7-troubleshooting-common-expo-issues)
27
+
28
+ ---
29
+
30
+ ## 1. Understanding Expo & Native Widgets Architecture
31
+
32
+ ### ⚠️ Why Expo Go is Not Supported
33
+ - **Expo Go** is a pre-compiled native binary containing a fixed set of Expo runtime modules.
34
+ - iOS **WidgetKit** (Home Screen Widgets) and **ActivityKit** (Live Activities & Dynamic Island) require an independent, dedicated native process called an **App Extension Target (`.appex`)**.
35
+ - Android similarly requires custom `AppWidgetProvider` declarations and services in `AndroidManifest.xml`.
36
+ - Therefore, **Expo Go cannot run native widgets**. You must use **Expo Prebuild / Expo Dev Client (`npx expo run:ios` / `npx expo run:android`)** or **EAS Build**.
37
+
38
+ ### 🌟 The Solution: Expo Config Plugin & Continuous Native Generation (CNG)
39
+ `react-native-live-widgets` includes a turnkey **Expo Config Plugin (`app.plugin.js`)** and **CLI Wizard**:
40
+ - Automatically injects `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` into `Info.plist`.
41
+ - Automatically configures `com.apple.security.application-groups` in your iOS Entitlements file.
42
+ - Adds real-time notification permissions (`POST_NOTIFICATIONS`) to Android.
43
+ - Automatically scaffolds and injects the Xcode `LiveWidgetsExtension` target with Swift templates and renderers **without manually opening Xcode**.
44
+
45
+ ---
46
+
47
+ ## 2. Official Expo Demo Repository (LiveWidgetsExampleExpo)
48
+
49
+ To explore a 100% pre-configured, production-ready Expo showcase project, visit the official demo repository:
50
+
51
+ 👉 **GitHub Repository:** **[https://github.com/React-Native-Vu/LiveWidgetsExampleExpo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)**
52
+
53
+ ### ✨ What’s Inside the Demo:
54
+ - 🚀 **Expo SDK 58 + React Native 0.88 + 100% TypeScript**.
55
+ - 🛠️ **Pre-configured Expo Config Plugin**: App Groups `group.com.reactnativevu.livewidgetsexampleexpo`.
56
+ - 🎨 **5 Real-World UI Presets**:
57
+ 1. **📊 Executive KPI Dashboard**: Circular progress, weekly sales chart, and live syncing.
58
+ 2. **☕ Coffee Delivery Tracker**: Dynamic Island countdown and lock screen order card.
59
+ 3. **✅ Interactive Task Checklist**: Direct check-off interaction on your Home Screen widget without opening the app.
60
+ 4. **🎵 Music & Audio Player**: Continuous animated audio waveform (Equalizer) on Dynamic Island.
61
+ 5. **✈️ Flight Status**: Route trajectory bar, gate details, and departure countdown.
62
+ - 🔄 **Bidirectional Action Dispatcher**: Tapping `[+]` or `[-]` on Home Screen widgets executes TypeScript callbacks in your app in real-time.
63
+
64
+ ### ⚡ Clone & Run in Under 2 Minutes:
65
+ ```bash
66
+ # 1. Clone the repository
67
+ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
68
+ cd LiveWidgetsExampleExpo
69
+
70
+ # 2. Install dependencies
71
+ npm install
72
+
73
+ # 3. Generate native folders
74
+ npx expo prebuild
75
+
76
+ # 4. Run automated widget target injection
77
+ npm run setup:widgets
78
+
79
+ # 5. Launch on iOS Simulator or Android Emulator
80
+ npx expo run:ios
81
+ # or
82
+ npx expo run:android
83
+ ```
84
+
85
+ ---
86
+
87
+ ## 3. Step-by-Step Installation & Setup
88
+
89
+ ### Step 1: Install Package
90
+ In your Expo project root:
91
+ ```bash
92
+ npx expo install react-native-live-widgets
93
+ ```
94
+
95
+ ---
96
+
97
+ ### Step 2: Configure `app.json` (Expo Config Plugin)
98
+ Open `app.json` and add the `react-native-live-widgets` plugin under `expo.plugins`:
99
+
100
+ ```json
101
+ {
102
+ "expo": {
103
+ "name": "MyExpoApp",
104
+ "slug": "my-expo-app",
105
+ "version": "1.0.0",
106
+ "ios": {
107
+ "bundleIdentifier": "com.yourcompany.myexpoapp",
108
+ "supportsTablet": true
109
+ },
110
+ "android": {
111
+ "package": "com.yourcompany.myexpoapp"
112
+ },
113
+ "plugins": [
114
+ [
115
+ "react-native-live-widgets",
116
+ {
117
+ "appGroup": "group.com.yourcompany.myexpoapp",
118
+ "enableLiveActivities": true,
119
+ "frequentUpdates": true
120
+ }
121
+ ]
122
+ ]
123
+ }
124
+ }
125
+ ```
126
+
127
+ #### Plugin Options Reference:
128
+ | Property | Type | Required | Default | Description |
129
+ | :--- | :--- | :---: | :---: | :--- |
130
+ | `appGroup` | `string` | **Yes** | `group.<bundleId>` | App Group identifier for instant data sharing between Main App and WidgetKit |
131
+ | `enableLiveActivities` | `boolean` | No | `true` | Enables Live Activities on Lock Screen and Dynamic Island |
132
+ | `frequentUpdates` | `boolean` | No | `true` | Enables high-frequency push updates (iOS 16.2+) |
133
+
134
+ ---
135
+
136
+ ### Step 3: Run Expo Prebuild
137
+ Generate clean native folders (`ios/` and `android/`):
138
+ ```bash
139
+ npx expo prebuild
140
+ ```
141
+
142
+ ---
143
+
144
+ ### Step 4: Run CLI Wizard for Widget Extension
145
+ Run the library's automated setup wizard to link the extension target:
146
+ ```bash
147
+ npx react-native-live-widgets init --group group.com.yourcompany.myexpoapp
148
+ ```
149
+
150
+ **What the CLI Wizard does automatically:**
151
+ 1. Configures the App Group into `<AppName>.entitlements`.
152
+ 2. Generates the `ios/LiveWidgetsExtension/` directory containing:
153
+ - `LiveWidgetsBundle.swift` (with 5 built-in interactive widget presets).
154
+ - `Info.plist` (for Extension).
155
+ - `LiveWidgetsExtension.entitlements` (for Extension).
156
+ - Copies Swift models, layout engines, and UI renderers into `Shared/`.
157
+ 3. Injects the `LiveWidgetsExtension` target into Xcode's `project.pbxproj`:
158
+ - Dedicated `PBXSourcesBuildPhase` (preventing `@main` duplicate errors with `AppDelegate.swift`).
159
+ - Links `WidgetKit.framework` and `SwiftUI.framework`.
160
+ - Sets deployment target to iOS 16.4+.
161
+ - Adds the target dependency under `Embed App Extensions`.
162
+ 4. Adds the pod dependency to `Podfile` and executes `pod install`.
163
+ 5. Injects required Android permissions into `AndroidManifest.xml`.
164
+
165
+ > [!TIP]
166
+ > Add a shortcut to your `package.json` for quick maintenance:
167
+ > ```json
168
+ > "scripts": {
169
+ > "setup:widgets": "npx react-native-live-widgets init --group group.com.yourcompany.myexpoapp"
170
+ > }
171
+ > ```
172
+
173
+ ---
174
+
175
+ ## 3. Running & Testing on Simulators & Devices
176
+
177
+ ### Run on iOS Simulator
178
+ ```bash
179
+ npx expo run:ios
180
+ ```
181
+ > [!IMPORTANT]
182
+ > - Dynamic Island testing requires a simulated device with a Dynamic Island (e.g., **iPhone 14 Pro, iPhone 15, iPhone 16, or iPhone 17**).
183
+ > - Live Activities require iOS 16.1+.
184
+
185
+ ### Run on Android Emulator
186
+ ```bash
187
+ npx expo run:android
188
+ ```
189
+
190
+ ---
191
+
192
+ ### Adding Home Widgets and Live Activities on Simulator
193
+
194
+ #### 1. Add Home Screen Widget on iOS Simulator:
195
+ 1. Press `Cmd + Shift + H` to return to the iOS Home Screen.
196
+ 2. Long-press an empty space until the app icons begin to jiggle.
197
+ 3. Tap the **[+]** button in the top-left corner.
198
+ 4. Search for your app name (e.g., `LiveWidgetsExampleExpo`).
199
+ 5. Choose any of the 5 available widget templates and tap **Add Widget**.
200
+
201
+ #### 2. Start Live Activity & Dynamic Island:
202
+ - Open your app and tap **"Start Live Activity"**.
203
+ - Lock the screen (`Cmd + L`) or swipe down from the top to view the Lock Screen card and Dynamic Island expanded banner!
204
+
205
+ ---
206
+
207
+ ## 4. EAS Build Configuration (Expo Application Services)
208
+
209
+ ### Register App Groups & Extension on Apple Developer
210
+ 1. Go to [Apple Developer Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list).
211
+ 2. **App Groups**:
212
+ - Create an App Group identifier (e.g., `group.com.yourcompany.myexpoapp`).
213
+ 3. **App Identifiers**:
214
+ - Edit your Main App ID (`com.yourcompany.myexpoapp`) -> Enable **App Groups** (link the group) -> Enable **Live Activities**.
215
+ - Create a second App ID for the Extension:
216
+ - **Identifier:** `com.yourcompany.myexpoapp.LiveWidgetsExtension`
217
+ - Enable **App Groups** and link to the same group.
218
+
219
+ ---
220
+
221
+ ### Configure `eas.json`
222
+ ```json
223
+ {
224
+ "cli": {
225
+ "version": ">= 10.0.0"
226
+ },
227
+ "build": {
228
+ "development": {
229
+ "developmentClient": true,
230
+ "distribution": "internal",
231
+ "ios": {
232
+ "simulator": true
233
+ }
234
+ },
235
+ "preview": {
236
+ "distribution": "internal",
237
+ "ios": {
238
+ "simulator": false
239
+ }
240
+ },
241
+ "production": {
242
+ "autoIncrement": true
243
+ }
244
+ },
245
+ "submit": {
246
+ "production": {}
247
+ }
248
+ }
249
+ ```
250
+
251
+ ---
252
+
253
+ ### Provisioning Profiles for Extension
254
+ When executing EAS Build:
255
+ ```bash
256
+ eas build --platform ios --profile production
257
+ ```
258
+ EAS CLI detects the auxiliary `LiveWidgetsExtension` target in Xcode and prompts you to generate and manage its provisioning profile:
259
+ - Select **Yes** to let EAS automate credentials for both Main App and Extension.
260
+
261
+ ---
262
+
263
+ ## 5. TypeScript Example for Expo (Widgets & Live Activity)
264
+
265
+ ```tsx
266
+ import React, { useEffect, useState } from 'react';
267
+ import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
268
+ import {
269
+ LiveActivity,
270
+ Widget,
271
+ UI,
272
+ SharedStorage,
273
+ } from 'react-native-live-widgets';
274
+
275
+ const APP_GROUP = 'group.com.yourcompany.myexpoapp';
276
+
277
+ export default function App() {
278
+ const [counter, setCounter] = useState(0);
279
+
280
+ useEffect(() => {
281
+ SharedStorage.setAppGroup(APP_GROUP);
282
+
283
+ // Two-way interactive action handler from Widget buttons
284
+ const unsubscribe = LiveActivity.registerActionHandler((action, payload) => {
285
+ console.log('Action received from Widget:', action, payload);
286
+ if (action === 'INCREMENT') {
287
+ setCounter((prev) => {
288
+ const next = prev + 1;
289
+ updateWidget(next);
290
+ return next;
291
+ });
292
+ }
293
+ });
294
+
295
+ return () => unsubscribe();
296
+ }, []);
297
+
298
+ const updateWidget = (val: number) => {
299
+ Widget.reload('main', {
300
+ layout: UI.VStack({
301
+ alignment: 'center',
302
+ padding: 16,
303
+ background: '#0F172A',
304
+ children: [
305
+ UI.Text('EXPO WIDGET COUNTER', { color: '#94A3B8', fontSize: 12, fontWeight: 'bold' }),
306
+ UI.Text(`${val}`, { color: '#38BDF8', fontSize: 40, fontWeight: 'heavy' }),
307
+ UI.Button('+1 INCREMENT', {
308
+ action: 'INCREMENT',
309
+ backgroundColor: '#0284C7',
310
+ textColor: '#FFFFFF',
311
+ }),
312
+ ],
313
+ }),
314
+ });
315
+ };
316
+
317
+ const startLiveActivity = async () => {
318
+ await LiveActivity.start({
319
+ activityName: 'ExpoTask',
320
+ appGroup: APP_GROUP,
321
+ layout: UI.VStack({
322
+ padding: 16,
323
+ background: '#020617',
324
+ children: [
325
+ UI.Text('🚀 Live Activity from Expo SDK!', { color: '#F8FAFC', fontSize: 16, fontWeight: 'bold' }),
326
+ UI.Progress(0.8, { style: 'bar', tintColor: '#38BDF8', height: 6 }),
327
+ ],
328
+ }),
329
+ dynamicIsland: {
330
+ compactLeading: UI.Text('🚀', { fontSize: 14 }),
331
+ compactTrailing: UI.Text('80%', { color: '#38BDF8', fontSize: 12, fontWeight: 'bold' }),
332
+ expanded: {
333
+ leading: UI.Text('EXPO LIVE', { color: '#94A3B8', fontSize: 11 }),
334
+ trailing: UI.Text('80%', { color: '#38BDF8', fontSize: 18, fontWeight: 'bold' }),
335
+ center: UI.Progress(0.8, { style: 'bar', tintColor: '#38BDF8', height: 6 }),
336
+ },
337
+ },
338
+ });
339
+ };
340
+
341
+ return (
342
+ <View style={styles.container}>
343
+ <Text style={styles.title}>Expo Live Widgets Demo</Text>
344
+ <Text style={styles.counter}>Count: {counter}</Text>
345
+
346
+ <TouchableOpacity style={styles.btn} onPress={() => updateWidget(counter + 1)}>
347
+ <Text style={styles.btnText}>Update Home Widget</Text>
348
+ </TouchableOpacity>
349
+
350
+ <TouchableOpacity style={[styles.btn, styles.btnLive]} onPress={startLiveActivity}>
351
+ <Text style={styles.btnText}>Start Live Activity</Text>
352
+ </TouchableOpacity>
353
+ </View>
354
+ );
355
+ }
356
+
357
+ const styles = StyleSheet.create({
358
+ container: { flex: 1, backgroundColor: '#090D16', justifyContent: 'center', alignItems: 'center', padding: 20 },
359
+ title: { fontSize: 24, fontWeight: 'bold', color: '#FFFFFF', marginBottom: 12 },
360
+ counter: { fontSize: 18, color: '#38BDF8', marginBottom: 24 },
361
+ btn: { backgroundColor: '#2563EB', paddingHorizontal: 24, paddingVertical: 14, borderRadius: 12, marginVertical: 8, width: '100%', alignItems: 'center' },
362
+ btnLive: { backgroundColor: '#059669' },
363
+ btnText: { color: '#FFFFFF', fontWeight: 'bold', fontSize: 16 },
364
+ });
365
+ ```
366
+
367
+ ---
368
+
369
+ ## 6. Troubleshooting Common Expo Issues
370
+
371
+ ### 1. `[react-native-live-widgets] Native module not found`
372
+ - **Cause:** Running via **Expo Go**.
373
+ - **Fix:** Native widgets require custom native binaries. Run `npx expo prebuild` and start using `npx expo run:ios` or `npx expo run:android`.
374
+
375
+ ### 2. `client is not entitled` error in logs
376
+ - **Cause:** Missing App Group entitlement.
377
+ - **Fix:** Ensure both `<AppName>.entitlements` and `LiveWidgetsExtension.entitlements` contain `com.apple.security.application-groups` with identical App Group names.
378
+
379
+ ### 3. `'main' attribute can only apply to one type in a module`
380
+ - **Cause:** `LiveWidgetsBundle.swift` got attached to the main app target instead of the extension target.
381
+ - **Fix:** Run the latest `npx react-native-live-widgets init` wizard which properly isolates target build phases.
382
+
383
+ ### 4. Metro Bundler: `Unable to resolve module react-native/asset-registry`
384
+ - **Cause:** Metro hierarchical lookup resolving conflicting packages in monorepos or local `file:...` dependencies.
385
+ - **Fix:** Configure `metro.config.js`:
386
+ ```javascript
387
+ const { getDefaultConfig } = require('expo/metro-config');
388
+ const path = require('path');
389
+
390
+ const config = getDefaultConfig(__dirname);
391
+ config.resolver.nodeModulesPaths = [
392
+ path.resolve(__dirname, 'node_modules'),
393
+ ];
394
+ config.resolver.disableHierarchicalLookup = true;
395
+
396
+ module.exports = config;
397
+ ```
398
+
399
+ ---
400
+
401
+ ## 7. Resources & Links
402
+ - ⚡ **Full Expo Demo App:** [LiveWidgetsExampleExpo on GitHub](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
403
+ - ⚛️ **Bare React Native Demo:** [LiveWidgetsExample on GitHub](https://github.com/React-Native-Vu/LiveWidgetsExample)
404
+ - 📖 **Full English Guide:** [GUIDE-EN.md](./GUIDE-EN.md)
405
+ - 🇻🇳 **Hướng dẫn Tiếng Việt:** [GUIDE-VI.md](./GUIDE-VI.md)