Skip to content

0007 expo and electron

github-actions[bot] edited this page Nov 17, 2026 · 1 revision

One Expo app, wrapped in Electron for desktop

Status: accepted · Implementation: skeleton · Date: 2026-11-17 · Supersedes: 0004

Partly supersedes ADR 0004: desktop is added as a fourth platform. The rest of 0004 stands. The on-device database and the UI kit get their own records. Spike, 2026-11-17: one screen using packages/core and a counter in expo-sqlite rendered and kept its value across a restart on the iOS simulator, an Android emulator, web (dev server and exported build) and Electron (run from source and packaged unsigned). Correction to the consequences: in Chromium the web build worked from a plain static server with no cross-origin isolation headers, using the async SQLite API only, so the hosting limit is not confirmed. Safari and Firefox were not tested.

Context

ADR 0004 targets iOS, Android and web and leaves the stack open. Desktop is now wanted as well, as a real downloadable app. One person builds librelifts, so four platforms have to come from as close to one codebase as possible, in TypeScript.

Two stacks fit:

  • One web UI everywhere: a web app, wrapped by Capacitor for the stores and by Electron for desktop. The most shared code and the simplest desktop story. On phones it is a web view, and platform features come through plugins or hand-kept native projects.
  • One Expo app: React Native on iOS and Android, React Native Web in the browser, and Electron around the web build. Native views on phones; a heavier web build.

A workout tracker is used on the phone, in the gym. The Later tier of docs/parity.md (Apple Health, Health Connect, widgets, Live Activities, Apple Watch) is all native-platform work.

Decision

  • Desktop is a fourth platform: macOS, Windows and Linux.
  • One Expo app (React Native, React Native Web, Expo Router) serves iOS, Android and web. The web build is a single-page app (web.output: "single").
  • Electron wraps the web build for desktop. The shell serves the exported files from its own app:// protocol and adds nothing to the UI.
  • Shared rules (progression, deloads) live in plain TypeScript with no React or React Native imports, so every platform runs the same code (ADR 0008).

Consequences

  • Phones get native views, and health, widget and watch work can go through Expo modules and config plugins.
  • The web build is heavier than a hand-written web app, and the desktop app is that web build: desktop gets no native widgets.
  • The Electron shell is ours to write and keep up; Expo's own Electron adapter is archived.
  • SQLite in the browser needs cross-origin isolation headers, so the web app can only be hosted where response headers can be set.
  • Each Expo SDK upgrade is one upgrade for three platforms, and one place for all three to break.

Clone this wiki locally