OpenCode Mobile is built with Expo and React Native.
- Node.js 22.13+ (the range in
package.jsonenginesis authoritative;.nvmrcpins 22) - npm
- Android Studio / Xcode for native builds
The unit suite runs under Vitest 5, which requires Node ^22.12.0 || ^24.0.0 || >=26.0.0. Older Node versions will fail to start the test runner.
If the working tree lives on a shared or network drive, macOS may leave
._*AppleDouble sidecar files behind. They are gitignored, but delete them before copying the tree to a build/test mirror so they never reach a bundle or native project.
-
Clone the repository and install dependencies:
git clone https://github.com/alvarolorentedev/opencode-mobile.git cd opencode-mobile npm install -
Start the development server:
npm run start
-
For a development client build:
npm run start:dev-client
Native Cloud Link is available in every build. Purchase/Restore requires a native development or store build, not Expo Go. Use
EXPO_APP_VARIANT=development npm run start:dev-clientfor the separate dev app. Cloud Link routes real purchases tohttps://api.opencodecloud.linkand test purchases tohttps://apistaging.opencodecloud.linkautomatically. No manual URL configuration is needed. The resolved environment survives relaunch. Products come from its backend catalog, never app configuration. See Cloud Link prerequisites and validation.
Expo publishes official AI agent skills for generic Expo and React Native work
(npx skills add expo/skills --global --agent codex, or the official Expo plugin for Claude Code / Codex). They
complement this repository's AGENTS.md, design system, and fake-server
contract; when generic advice conflicts with the repo docs, the repo wins. Do
not vendor the skills or add them as project dependencies.
For native work, use Expo's expo-overview, expo-upgrade, expo-module and
expo-dev-client skills as applicable. Discover libraries in the versioned SDK
58 documentation and Expo's bundled dependency mapping. Install native packages
with npx expo install, review their config plugins and FOSS impact, then use
npx expo install --check and npx expo-doctor. Do not upgrade unrelated SDKs or
tools, force peer resolution, or edit generated native projects as the solution.
The optional Expo MCP endpoint is https://mcp.expo.dev/mcp (OAuth). The official
Expo plugin registers it; otherwise follow the official MCP setup.
The development-only expo-mcp package remains disabled unless the developer
starts Expo with EXPO_UNSTABLE_MCP_SERVER=1. Local capabilities require Expo CLI
and MCP to authenticate with the same Expo account. Normal development and CI commands
do not set that flag. Local capabilities send inspected data through Expo's remote
service: use synthetic accounts/data and keep credentials out of captures.
Direct tools remain the fallback: use the existing Android/iOS build commands,
the first failing Gradle task with --stacktrace, dependency inspection,
adb logcat, and Xcode's build log/signing diagnostics. Rebuild the development
client after native changes. Simulator/MCP evidence cannot replace physical-device
voice/keyboard acceptance, signed store-update tests or release/FOSS builds. See
the validation matrix and native ownership.
npm run lint # Run linter
npm run typecheck # Type checking
npm run test:e2e:smoke # Critical Playwright flows
npm run test:e2e:web # Full end-to-end suite
npm run storybook # Open the reusable component catalog
npm run build:storybook # Build-check the Storybook catalog
npm run android # Build Android app
npm run ios # Build iOS app
npm run prebuild:ios # Generate iOS native project
npm run build:ios:local # Build iOS release archive locallyBuild a production Android release:
npm run build:androidBuild a development client:
npm run build:development:androidBuild the de-Googled FOSS variant (published to F-Droid; excludes Play Billing, ML Kit barcode scanning, and Firebase Cloud Messaging):
npm run build:foss:androidInstall android/app/build/outputs/apk/debug/app-debug.apk (OpenCode Mobile
Dev) and use EXPO_APP_VARIANT=development npm run start:dev-client. Both prebuild and Gradle use the
development variant. Release APKs are built by the v* tag workflow and also
expose Cloud Link subscriptions. See Cloud Link for native store,
trusted environment, and sandbox configuration. See
F-Droid and FOSS builds for the FOSS variant's scope and distribution.
Release Automation (.github/workflows/release.yml):
- Pushes to
mainand pull requests runci.yml: static checks, Vitest/architecture, fake-server validation, Storybook, FOSS preparation and critical Playwright smoke flows - A
v*tag push runsrelease.ymlautomatically. It verifies the tag,app.config.tsversion, Android versionCode, iOS buildNumber and changelog; requires the tag commit to belong tomain; runs full validation once; and builds Android Play, FOSS Android and signed iOS in parallel. The Play changelog (fastlane/metadata/android/en-US/changelogs/<versionCode>.txt) must stay within Google Play's 500-character release-notes limit or distribution fails - Android release artifacts are
arm64-v8aonly. 32-bit-only Android devices are unsupported. There is no ABI override or emulator-specific release build - Validated Android builds upload to Google Play internal testing; the signed IPA uploads to TestFlight when App Store Connect API credentials are configured
- The GitHub Release is created as a draft only after validation, builds and store uploads succeed, then published with the APKs, IPA, AAB, mapping and SHA256SUMS.txt
- Nothing is automatically promoted to a production store track.
workflow_dispatchis recovery-only and requires an existing tag - Google Play in-app update priority is set from the optional
update_priorityinput (0–5, default0) and sent asinAppUpdatePrioritywith the existing internal-track upload. Automatic tag releases use0, which keeps updates flexible. Manual dispatches may pass4or5for an emergency release that uses Play's immediate flow. The value is validated before upload and recorded in the job summary - Static release verification covers signing, package identity, version, ABI, native libraries, R8/ProGuard safety, the WorkManager constructor, FOSS exclusions and 16 KB page-size alignment. It cannot guarantee successful device startup; Google Play internal testing and TestFlight are the real-device validation environments
- See Android Build / Release Notes
Normal release (flexible, the default):
- Bump
version,android.versionCodeandios.buildNumber, update the Play changelog, commit and push tomain. - Push the
v<version>tag.release.ymlpublishes with priority0: the app downloads in the background and shows its own restart toast.
Emergency release (immediate):
- Complete the normal release steps, then push the tag and cancel the automatic run before its
distribute-playjob if you need to publish with priority instead. - Run the
Releaseworkflow manually for that tag withupdate_priority4or5. Play then requires its full-screen update flow for users below that version.
Priority is per release, not per app: Google Play cannot change it after the release is rolled out, and a device may observe the highest priority across skipped versions and other tracks. A priority of 4–5 therefore affects devices that jump from any older version, even if an intermediate release was normal. Do not use 4–5 for routine releases. This is Google Play's in-app update priority, unrelated to notification priority or the version number.
For a free Apple Personal Team development build, choose a bundle identifier that is unique to your Apple account and pass it to the helper command:
EXPO_IOS_BUNDLE_ID=com.example.yourname.opencode npm run ios:personal-team -- --deviceThe helper removes only the aps-environment entitlement that Personal Teams
cannot provision. This local build cannot receive push notifications. Ordinary
iOS, CI, and paid-team builds keep the configured bundle identifiers and push
entitlement because the opt-out is unset.
Build a local iOS release:
npm run build:ios:localRelease Automation (.github/workflows/release.yml):
- A
v*tag builds and signs the iOS archive automatically in parallel with Android - The IPA is verified for signature, bundle identifier, version, build number, production push entitlement and provisioning-profile identity
- When App Store Connect API credentials are configured, the IPA is validated and uploaded to TestFlight automatically
- The signed IPA is attached to the GitHub Release. No manual iOS workflow dispatch is required
- App Store production submission and phased release remain separate manual store-console actions
npm run test:ci:staticruns lint, app type-checking, the typed-test type-check (npm run typecheck:tests, viatsconfig.tests.json), and the Vitest suites (tests/vitest/)- Flow validation runs against the fake OpenCode server in
tests/fake-opencode/server.mjs - End-to-end suite uses Playwright (
tests/e2e/*.spec.mjs, split by domain overtests/e2e/helpers/flows.mjs) npm run test:e2e:smokeruns the critical flows;npm run test:e2e:web:isolatedallocates fresh ports for concurrent local runs;npm run validate:fastis an optional focused loopci.ymlruns the smoke set in one job with four workers;release.ymlruns the full Playwright suite once on a version tag. Each worker has its own fake V1/V2 pair, and the worker backend resets before every test- Full testing strategy documented in
docs/engineering/testing-overview.md; remaining deferred test work indocs/engineering/known-gaps.md
Connection settings are configured inside the app. By default, the app expects an OpenCode server at http://127.0.0.1:4096.
Local configuration files (.env, config.json) are gitignored for security.
Android Play updates use flexible-first expo-in-app-updates and require a signed Play-installed
production app for runtime validation. FOSS excludes the package. iOS is disabled
until the verified public listing ID is supplied as EXPO_IOS_APP_STORE_ID;
EXPO_IOS_APP_STORE_COUNTRY is optional. See app updates.