|
1 | | -# @10play/expo-air |
2 | | - |
3 | | -Vibe Coding for React-Native - AI-powered on-device development with Claude. |
4 | | - |
5 | | -## Features |
6 | | - |
7 | | -- Floating widget overlay on your iOS device |
8 | | -- Send prompts to Claude directly from your phone |
9 | | -- Real-time code changes via Expo Metro |
10 | | -- Git status monitoring |
11 | | -- Tunnel support for remote development |
12 | | - |
13 | | -## Requirements |
14 | | - |
15 | | -- Expo SDK 54+ |
16 | | -- iOS 15.1+ (iOS only in v0) |
17 | | -- Node.js 18+ |
18 | | - |
19 | | -## Installation |
20 | | - |
21 | | -### 1. Install the package |
22 | | - |
23 | | -```bash |
24 | | -npm install @10play/expo-air |
25 | | -``` |
26 | | - |
27 | | -### 2. Initialize in your project |
| 1 | +<p align="center"> |
| 2 | + <img src="assets/cover.svg" alt="expo-air" /> |
| 3 | +</p> |
28 | 4 |
|
29 | 5 | ```bash |
30 | 6 | npx expo-air init |
31 | 7 | ``` |
32 | 8 |
|
33 | | -This will: |
34 | | -- Create `.expo-air.json` configuration file |
35 | | -- Add the plugin to your `app.json` |
36 | | -- Update `.gitignore` |
37 | | -- Run `expo prebuild` to generate native iOS code |
38 | | - |
39 | | -### 3. Start development |
40 | | - |
41 | | -```bash |
42 | | -npx expo-air start |
43 | | -``` |
44 | | - |
45 | | -This starts: |
46 | | -- Widget Metro server (port 8082) |
47 | | -- Prompt server (port 3847) |
48 | | -- App Metro server (port 8081) |
49 | | -- Cloudflare tunnels for remote access (optional) |
50 | | - |
51 | | -The widget will appear automatically when your app launches in DEBUG mode. |
52 | | - |
53 | | -## Usage |
54 | | - |
55 | | -### CLI Commands |
56 | | - |
57 | | -```bash |
58 | | -# Initialize expo-air in your project |
59 | | -npx expo-air init |
60 | | -npx expo-air init --force # Overwrite existing config |
61 | | -npx expo-air init --skip-prebuild # Skip running expo prebuild |
62 | | - |
63 | | -# Start the development environment |
64 | | -npx expo-air start |
65 | | -npx expo-air start --no-tunnel # Skip tunnel (local network only) |
66 | | -npx expo-air start --no-build # Skip building the app |
67 | | -npx expo-air start --no-server # Skip starting the WebSocket server |
68 | | - |
69 | | -# Start only the WebSocket server |
70 | | -npx expo-air server |
71 | | -``` |
72 | | - |
73 | | -### Port Options |
74 | | - |
75 | | -```bash |
76 | | -npx expo-air start \ |
77 | | - --port 3847 \ # Prompt server port |
78 | | - --widget-port 8082 \ # Widget Metro port |
79 | | - --metro-port 8081 # App Metro port |
80 | | -``` |
81 | | - |
82 | | -## Configuration |
83 | | - |
84 | | -### .expo-air.json |
85 | | - |
86 | | -Configuration file created by `expo-air init`: |
87 | | - |
88 | | -```json |
89 | | -{ |
90 | | - "autoShow": true, |
91 | | - "ui": { |
92 | | - "bubbleSize": 60, |
93 | | - "bubbleColor": "#000000" |
94 | | - } |
95 | | -} |
96 | | -``` |
97 | | - |
98 | | -| Option | Type | Default | Description | |
99 | | -|--------|------|---------|-------------| |
100 | | -| `autoShow` | boolean | `true` | Auto-show widget on app launch | |
101 | | -| `ui.bubbleSize` | number | `60` | Size of the floating bubble | |
102 | | -| `ui.bubbleColor` | string | `"#000000"` | Color of the floating bubble | |
103 | | - |
104 | | -### .expo-air.local.json (gitignored) |
105 | | - |
106 | | -Auto-generated file containing tunnel URLs for the current session: |
107 | | - |
108 | | -```json |
109 | | -{ |
110 | | - "serverUrl": "wss://...", |
111 | | - "widgetMetroUrl": "https://...", |
112 | | - "appMetroUrl": "https://..." |
113 | | -} |
114 | | -``` |
115 | | - |
116 | | -## How It Works |
117 | | - |
118 | | -1. **App launches** - `ExpoAirAppDelegateSubscriber` triggers (DEBUG builds only) |
119 | | -2. **Config loaded** - Settings read from `Info.plist` (set by plugin during prebuild) |
120 | | -3. **Widget loads** - `FloatingBubbleManager` loads widget bundle from Metro server |
121 | | -4. **Connection established** - Widget connects to prompt server via WebSocket |
122 | | -5. **Ready to vibe** - Send prompts to Claude from your device |
123 | | - |
124 | | -## Development Mode Only |
125 | | - |
126 | | -The widget is designed for development only and will **never appear in production builds**. This is enforced via: |
127 | | - |
128 | | -- `#if DEBUG` guards in native Swift code |
129 | | -- Widget loads from Metro dev server (no bundled JS) |
130 | | -- No impact on release builds |
131 | | - |
132 | | -## Troubleshooting |
133 | | - |
134 | | -### Widget not appearing |
135 | | - |
136 | | -1. Ensure you're running a DEBUG build (not release/production) |
137 | | -2. Check that Metro servers are running (`npx expo-air start`) |
138 | | -3. Verify `autoShow: true` in `.expo-air.json` |
139 | | -4. Check Xcode console for `[expo-air]` logs |
140 | | - |
141 | | -### Connection issues |
142 | | - |
143 | | -1. For local development, ensure device is on same WiFi as your computer |
144 | | -2. For remote development, use tunnels (`npx expo-air start` enables by default) |
145 | | -3. Check that ports 3847, 8081, 8082 are not blocked |
146 | | - |
147 | | -### Prebuild issues |
| 9 | +Connect your device |
148 | 10 |
|
149 | | -If prebuild fails, try: |
150 | 11 | ```bash |
151 | | -npx expo prebuild --platform ios --clean |
| 12 | +npx expo-air fly |
152 | 13 | ``` |
153 | 14 |
|
154 | | -## License |
| 15 | +Boom. You can work from anywhere. |
155 | 16 |
|
156 | | -MIT |
| 17 | +[Read the docs](https://expo-air.10play.dev/) |
0 commit comments