Work on the native app
The native app is paused since 2026-11-13 (why). Its nightly builds are off; the checks below still run when its code or a shared module changes.
On this page
mobile/app/ is the phone app in progress (OpenSpec change native-app-foundation): React Native with Expo, drawn with the system's own views, and sharing sync, ops, encryption, dates, recurrence and quick add with the web app. It is not the iPhone or Android shell in mobile/ios and mobile/android, which load the web app.
Without a Mac#
Most of the work needs only Linux and Node 24:
make app # npm ci in mobile/app, type-check, lint, the Jest tests, the shared module list
cd mobile/app && npx jest test/recurrence.test.ts
cd mobile/app && npx expo export --platform ios # bundles the JavaScript as the app would
make app installs the app's own dependencies and never web's; make check leaves it out unless you run make check APP=1. The iOS and Android builds run in CI, on a pull request that changes mobile/app/, so you do not need Xcode or the Android SDK. With an Android SDK, npx expo prebuild --platform android and ./gradlew :app:assembleDebug in mobile/app/android build it locally.
The native projects (ios/, android/) are generated by npx expo prebuild from app.config.ts and are never committed. Change the app's native setup there, or in a config plugin.
The shared library#
The app imports web/src/lib as @shared/*, through Metro (metro.config.js), Jest (jest.config.js) and TypeScript (tsconfig.json). Every package a shared module names comes from mobile/app/node_modules, so there is one React and the app needs nothing installed in web/.
- What the app may import. Only
@shared/*. ESLint refusesweb/src/app,web/src/uiand the browser-only packages (react-dom,dexie-react-hooks,prosemirror-*,maplibre-gl). - The host. A shared module never reads
window,document,navigator,localStorage,BroadcastChannelorindexedDBdirectly; it asksweb/src/lib/platform.ts. The app installs its implementation (src/platform.ts,src/host.ts) at start-up.make repo-checkfails on a browser global in a module listed inmobile/app/shared-modules.json. - The list.
node mobile/app/scripts/shared-modules.mjsprints the modules the app shares: the import graph (scripts/shared-graph.mjs) of the sync path and of every@shared/*module the app's code and tests import.--writerewritesshared-modules.json, andmake appfails when the file is stale. - Vite forms.
import.meta.globandimport.meta.env.MODEare compiled bybabel/vite-import-meta.js, so the shared i18n layer loads the same catalogs as the web app. - Vectors. The tests in
mobile/app/test/run the shared vectors (hybrid clock, recurrence, quick add, project flows, encryption) on the app's runtime against the same modules the web app runs. A change that breaks one fails in both.
The local database#
The shared modules call their database through web/src/lib/db.ts's tables (db.tasks.where('project_id').equals(id).toArray(), db.transaction('rw', …)), as on the web. On the web that is Dexie on IndexedDB. In the app it is an adapter on SQLite, mobile/app/src/storage/:
- How it is chosen.
db.tsdeclares its schema on a Dexie instance and asks the platform port for the database (platform.database?.(declared)). The web has no such member and opens the Dexie instance; the app answers withsqliteDatabase(declared, op-sqlite). Nothing in the web's bundle changes. - What it implements. Exactly the part of Dexie the shared modules call.
node mobile/app/scripts/dexie-surface.mjslists it with the type checker (every property access in a module ofshared-modules.jsonthat resolves to a declaration in Dexie's types) intosrc/storage/surface.json.make appfails when the file is stale, andtest/storage/surface.test.tsfails on a member the adapter lacks. A shared module that starts calling, say,Collection.modifyfailsmake appuntil the adapter has it. - Storage. One SQLite table per store: the primary key, the row as JSON, and a generated column per key path an index names, holding the value only when IndexedDB would index it. Every Dexie index is a SQL index. A read is one
JSON.parseof the whole result. - Transactions. A transaction is a SQLite transaction. Calls made inside it, across awaits, run on it; calls from outside wait until it ends, as IndexedDB queues them. The adapter tells them apart with Dexie's zones, which follow an
awaitonly becausebabel.config.jscompiles async functions to generators. Keep that plugin. - The phone's own indexes. Today and Inbox ask SQLite for their candidates (
src/storage/lists.ts) through indexes the web does not have (PHONE_INDEXESinschema.ts), then run the shared rules (todayList,inboxTasks,isTaskVisible,tasksIn) on them. They never read the whole tasks table. - Per account.
openAccount(server, userId)opens the account's file;forgetAccount()empties every table at sign-out, as on the web, and deletes the file.
The tests in mobile/app/test/storage/ run without a phone:
cd mobile/app && npx jest test/storage
conformance.test.tsruns each scenario twice ondb.ts's schema, on Dexie overfake-indexeddb(the web) and on the adapter overnode:sqlite(the phone, withnode:sqlitein place of op-sqlite, which is native), and expects the same results.shared.test.tsdoes the same with the shared modules themselves: pulled pages throughapplyOps, and local edits throughcreateTask,updateTaskand the rest, then compares every table.lists.test.tschecks that Today and Inbox from the indexes equal the web's lists over a generated account, and that SQLite uses the indexes.
The performance run (mobile/app/perf/, the job App builds / App performance) measures the same on the iOS simulator with the 10,000-task perfseed account. On a computer, perf/local.test.ts runs the session over node:sqlite (the commands are at its top).
Dependencies#
Every package is pinned exactly and has a line in mobile/app/DEPENDENCIES.md saying why; make repo-check fails otherwise. mobile/app/.npmrc installs only releases at least 14 days old. Dependabot proposes the app's updates once a week in one pull request.
CI lanes#
| Job | Runs when | What |
|---|---|---|
app-check (Linux) |
mobile/app/, a module in shared-modules.json, web/src/generated/opSchema.ts, web/src/locales/, the Makefile or the workflow changes |
make app |
App builds / App on iOS (macOS) |
a pull request that changes mobile/app/ |
expo prebuild, a Release simulator build without signing |
App builds / App on Android (Linux) |
the same | expo prebuild, a debug build, the unit tests |
App builds / App performance (macOS) |
by hand with gh workflow run app-native.yml --ref <branch> -f perf=true |
the perfseed account on the simulator: cold start to Today, Inbox, a 500-op pull page, memory, and a write that survives the app being killed |
A web-only pull request runs none of them, and a change to a shared module runs only app-check. Release tags do not wait for the app's builds: no release ships the app yet. The cases are in the path filter's test, scripts/repo-checks.test.mjs.