The best way to control Claude Code, Codex and more from any computer or phone

main
md 165 lines 6.38 KB
Rendered Raw
1 # T3 Code Mobile
2
3 > [!NOTE]
4 > To install the released app from the App Store or Google Play, see [Mobile app](../../docs/user/install.md#mobile-app). This guide covers building it from source.
5
6 ## Quickstart
7
8 > [!NOTE]
9 > Uses native modules so using Expo Go is not supported. You need to use the Expo Dev Client.
10
11 This app has three variants:
12
13 - `development`: Expo dev client, installable side-by-side as `T3 Code Dev`
14 - `preview`: persistent internal preview build, installable side-by-side as `T3 Code Preview`
15 - `production`: store/release build as `T3 Code`
16
17 Run commands from `apps/mobile`.
18
19 T3 Connect is optional and disabled in a fresh clone. Public configuration belongs in the
20 repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
21 [`../../.env.example`](../../.env.example).
22
23 ## Development
24
25 For simulator, emulator, or Android phone development, boot or connect a device, then install the
26 native client that matches this checkout before starting Metro:
27
28 ```bash
29 vp run mobile:install ios [simulator-udid]
30 # Or: vp run mobile:install android [emulator-or-phone-serial]
31 vp run dev:client
32 ```
33
34 The device argument can be omitted when exactly one device is booted or connected. The helper
35 compares this checkout's Expo fingerprint and the installed binary with its last install record,
36 and reuses a matching client. Otherwise it installs the build for that fingerprint from
37 `~/.cache/t3code/native-clients/artifacts`, then the shared task cache, and builds only when
38 neither has it. A build runs in the `Mobile Dev Client` workflow (Blacksmith runners with warm
39 Gradle and ccache state, and a macOS runner for iOS) when `gh` may dispatch workflows on
40 `pingdotgg/t3code` and HEAD is pushed; the helper waits for the client in the shared cache.
41 Otherwise, or when HEAD lacks your native edits or `T3_NATIVE_CLIENT_BUILD=local` is set, it builds
42 on this machine. Main's client is built there on every native change, so most checkouts hit. One iOS simulator build serves every iPhone and iPad simulator, and one APK per
43 ABI (x86_64 or arm64-v8a) serves every emulator and phone of that ABI. Build output goes to the
44 log file it prints (`T3_NATIVE_CLIENT_VERBOSE=1` streams it instead). Builds are shared back when
45 your task-cache login (`bash infra/task-cache/install.sh`) can write. `T3_NATIVE_CLIENT_CACHE=read`
46 skips the upload and `off` skips the shared cache. Physical iPhones still use `vp run ios:dev`.
47
48 `--session <name>` installs into an agent-device session opened elsewhere, such as a device pool
49 or a cloud simulator, instead of a local device: `vp run mobile:install android --session pool-1
50 --metro http://<this-machine>:8081`. It uses only the cached build (x86_64 by default; `--abi`
51 for ARM) and fails with the next step when no machine has built this fingerprint yet.
52
53 For a read-only decision, run `node ../../scripts/mobile-native-client.ts check <ios|android>
54 [device]`: exit 0 means compatible, 2 means an install is needed, and 1 means an operational error.
55 An externally installed client is unverified until the helper installs it once.
56
57 Start Metro for an already verified dev client:
58
59 ```bash
60 vp run dev:client
61 ```
62
63 Metro keeps its transform cache between ordinary starts. If the cache itself is causing stale or
64 invalid output, clear it for one development-client start:
65
66 ```bash
67 vp run dev:client:reset
68 ```
69
70 Run that reset once after installing or changing the Uniwind dependency patch. Cached transforms
71 can otherwise reference its previous pnpm package path. Ordinary Metro starts still keep the cache.
72
73 Component edits use Fast Refresh. See [mobile development lifecycle](../../docs/internals/mobile-development.md)
74 before changing runtime ownership or refresh behavior.
75
76 Build and run the local iOS dev client:
77
78 ```bash
79 vp run ios:dev
80 ```
81
82 After changing a native dependency patch, rerun CocoaPods before rebuilding an existing iOS
83 project. pnpm gives each patch hash a new package path; Pods can otherwise keep compiling the
84 previous directory.
85
86 If your Xcode account only has a Personal Team, use a bundle identifier you control and opt into the
87 reduced-capability local build. Personal Team builds omit the widget and share extensions, push
88 entitlement, and native Sign in with Apple entitlement; builds without this opt-in are unchanged.
89
90 ```bash
91 T3CODE_IOS_PERSONAL_TEAM=1 \
92 T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID=com.example.t3code.dev \
93 vp run ios:dev
94 ```
95
96 Build and install a self-contained Release app that does not need Metro:
97
98 ```bash
99 vp run ios:release
100 ```
101
102 The Personal Team equivalent also needs a unique bundle identifier:
103
104 ```bash
105 T3CODE_IOS_PERSONAL_TEAM=1 \
106 T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID=com.example.t3code \
107 vp run ios:release
108 ```
109
110 Build and run the local iOS preview app:
111
112 ```bash
113 vp run ios:preview
114 ```
115
116 Inspect the resolved Expo config for a variant:
117
118 ```bash
119 vp run config:dev
120 vp run config:preview
121 ```
122
123 Run static checks for mobile native code:
124
125 ```bash
126 node ../../scripts/mobile-native-static-check.ts
127 ```
128
129 The native lint task runs SwiftLint for Swift plus ktlint and detekt for Kotlin. Missing native tools are reported as warnings and skipped locally. CI installs the default toolset from `apps/mobile/Brewfile` before running the native checks.
130
131 ## EAS Builds
132
133 Preview and production variants use Expo fingerprinting so OTA updates only reach binaries with matching native dependencies, config plugins, and patches. CI uses the `preview:dev` profile to reuse a compatible native build when possible.
134
135 The development variant uses `appVersion` to avoid recalculating the native fingerprint for each Metro launch manifest. `MOBILE_VERSION_POLICY` can override either default. If you distribute a custom Release build with the development identity and publish OTA updates to it, set `MOBILE_VERSION_POLICY=fingerprint` for both its build and updates. Changing the runtime policy requires a native rebuild for OTA matching; an existing dev client can still load local Metro bundles.
136
137 For preview or production EAS environments, set `T3CODE_CLERK_PUBLISHABLE_KEY`,
138 `T3CODE_CLERK_JWT_TEMPLATE`, and `T3CODE_RELAY_URL`
139 as EAS environment variables. Expo config maps the canonical values into the mobile build.
140
141 Create a PR preview dev-client build manually:
142
143 ```bash
144 vp run eas:ios:preview:dev
145 ```
146
147 Create a cloud dev-client build:
148
149 ```bash
150 vp run eas:ios:dev
151 ```
152
153 Create a persistent preview build:
154
155 ```bash
156 vp run eas:ios:preview
157 ```
158
159 Android equivalents:
160
161 ```bash
162 vp run eas:android:dev
163 vp run eas:android:preview:dev
164 vp run eas:android:preview
165 ```