react-native-live-widgets 1.0.0 → 1.1.0
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.
- package/CHANGELOG.md +8 -0
- package/README.md +195 -49
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +2 -1
- package/app.plugin.js +114 -0
- package/assets/cross_platform_parity.png +0 -0
- package/assets/donate_qr.png +0 -0
- package/assets/dynamic_island_expanded.png +0 -0
- package/assets/home_widget_interactive.png +0 -0
- package/assets/lock_screen_live_activity.png +0 -0
- package/cli/setup.js +445 -48
- package/docs/EXPO-GUIDE-EN.md +405 -0
- package/docs/EXPO-GUIDE-VI.md +427 -0
- package/docs/GUIDE-EN.md +57 -14
- package/docs/GUIDE-VI.md +57 -14
- package/lib/builder.js +9 -13
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.js +6 -11
- package/lib/dispatcher.js.map +1 -1
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +40 -53
- package/lib/index.js.map +1 -1
- package/lib/types.js +1 -2
- package/lib/types.js.map +1 -1
- package/package.json +21 -4
- package/src/index.ts +12 -4
- 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)
|