ADR-002 — Cross-Platform Framework Selection¶
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-05-22 |
| Project | MPowerUP |
| Deciders | Kevin Crump |
Context¶
MPowerUP is a cross-platform mobile application serving vulnerable populations. Choosing a mobile framework is therefore not only an engineering decision — it is also a governance decision. The recurring question from funders, partners, and contributors:
Is React Native the only viable open-source cross-platform option for MPowerUP, given that it is ultimately steered by Meta?
The answer is no — but the realistic alternatives are narrower than the public framework landscape suggests, because MPowerUP's architecture is constrained more by what its load-bearing libraries need than by aesthetics.
Architectural constraints driving the choice¶
MPowerUP's core stack depends on JS-ecosystem-specific libraries that cannot easily be replaced:
| Existing dependency | Ecosystem coupling |
|---|---|
| Yjs + y-protocols | JS-native CRDT; one YDoc per Circle; Rust port (y-crdt / y-octo) lags in feature parity |
| js-libp2p (WebRTC + circuit-relay-v2 + KAD-DHT + noise + yamux) | JS implementation is the most feature-complete; Rust/Go DHT + WebRTC + circuit-relay parity is uneven |
| TweetNaCl (Ed25519, secretbox) | Trivially portable, but identity/Circle keypairs already live in expo-secure-store |
| WatermelonDB | JS + SQLite; tightly coupled to React Native's JSI |
| expo-secure-store | Platform keystore access through Expo's native module |
Any framework that is not a JS runtime on mobile forces porting or wrapping js-libp2p + Yjs — the load-bearing part of the architecture, not a swappable detail. That single constraint collapses the candidate list more than the "no tech giant" filter does.
Governance framing¶
"Tech giant backed" is a governance question, not a license question. The MIT license on React Native is permissive and fork-safe; the substantive risk is that Meta controls roadmap direction (e.g. the New Architecture rollout). That risk is real but bounded — RN has substantial outside contributors (Microsoft, Software Mansion, Expo Inc, Shopify, Callstack). A second governance dependency is Expo Inc, an independent VC-backed company that owns EAS, Expo Router, and the platform modules MPowerUP relies on. RN and Expo are treated as a bundled platform choice here because their fates ride together in practice.
Decision¶
Continue building MPowerUP on React Native 0.81 + Expo SDK 54, treated as a bundled platform choice.
Component breakdown¶
- React Native 0.81 (MIT, Meta-steered) — JS runtime on device, native bridge to platform APIs.
- Expo SDK 54 (MIT, Expo Inc) — build pipeline (EAS Build/Update), file-based routing (Expo Router), platform modules (
expo-secure-store,expo-location,expo-camera,expo-notifications,expo-background-fetch). - NativeWind v4 + React Native Paper — accessibility-friendly Material Design 3 UI.
- Yjs + js-libp2p + TweetNaCl + WatermelonDB — sync, networking, crypto, persistence — all run unmodified on this platform.
Governance surface (named explicitly)¶
| Dependency | Governance type | Notes |
|---|---|---|
| Meta | Single-company steward of RN core | MIT licensed; fork-able if needed |
| Expo Inc | VC-backed independent company | EAS pricing, acquisition, layoff risk |
| Software Mansion | Independent company | Maintains Reanimated, Screens — critical native pieces |
| Microsoft | Active contributor | Invested in RN survival via VS Code / Office mobile |
Neither dependency alone is a critical risk. Both together represent the cost of choosing this platform.
Consequences¶
Positive¶
- The existing JS-ecosystem stack runs unmodified — no porting work.
- Mature, accessible component ecosystem (React Native Paper MD3, Reanimated, Expo Router).
- EAS Build/Update is a turnkey CI/CD pipeline.
- Large hiring pool and active community — easier contributor onboarding (matters for a small non-profit).
- The architectural pattern (CRDT-per-Circle over libp2p WebRTC) was designed against RN's threading model — moving frameworks would re-litigate settled decisions.
Negative / trade-offs¶
- Meta governance: RN roadmap direction is set by Meta (e.g. the New Architecture rollout consumed significant ecosystem effort).
- Expo governance: Expo Inc is VC-backed; layoffs, acquisition, or EAS pricing changes are real risks BNI doesn't control.
- Dual-governance surface: two corporate dependencies in parallel, unlike a single-foundation framework.
- Lock-in cost: swapping RN later means rebuilding the UI layer, replacing WatermelonDB's JSI adapter, and reconfirming
js-libp2pWebRTC parity.
Neutral¶
- License is MIT — forking RN or Expo is technically possible if governance became blocking, though the practical maintenance cost is high.
- Does not foreclose web (Phase 5,
react-native-web) or desktop targets.
Alternatives considered¶
The genuine non-tech-giant options evaluated:
- NativeScript (OpenJS Foundation) — JS/TS with direct native API access; cleanest governance of any candidate; Yjs + TweetNaCl run unmodified. Rejected because:
[HYPOTHESIS]js-libp2p WebRTC + circuit-relay-v2 production parity on NativeScript is unverified (no confirmed deployment of this exact stack); materially smaller accessible-component ecosystem (no RN-Paper equivalent); WatermelonDB's JSI adapter is RN-specific. Strongest re-evaluation candidate if Meta governance becomes blocking. - Capacitor + Svelte / SolidJS / Vue (Ionic Inc, MIT) — WebView shell; strongest browser-API compatibility for the P2P stack. Rejected: WebView UX less native (matters for an accessibility-first app); accessibility parity needs rebuild; two governance deps remain. Second-strongest re-evaluation candidate.
- Tauri Mobile (Tauri Foundation / CommonsHaus) — Rust core + system WebView; strong governance. Rejected:
[HYPOTHESIS]2026 mobile maturity ~ Capacitor but thinner ecosystem; Rust↔WebView seam adds complexity. - Dioxus Mobile (community OSS) — Rust, React-like, alpha/beta mobile. Rejected: would require Rust ports of every dependency + full UI rewrite — a 12+ month rebuild.
- Slint (SixtyFPS GmbH) — experimental mobile; single small company; a toolkit, not a framework.
- Apache Cordova (ASF) — strictly dominated by Capacitor.
- "Vue instead of React" framing — there is no live Vue equivalent of React Native (Vue Native is unmaintained since ~2021). "Vue over React" reduces to NativeScript-Vue or Capacitor+Vue, both covered above. The component-layer governance is cleaner, but the load-bearing risk lives at the mobile-platform layer, which doesn't change with the component framework.
Detailed RN vs NativeScript comparison (5–10 year horizon)¶
NativeScript is the strongest re-evaluation candidate, so it warrants closer scrutiny.
| Axis | React Native | NativeScript |
|---|---|---|
| License | MIT | Apache 2.0 |
| Steward | Meta + major contributors | OpenJS Foundation; core team at nStudio (~5 people) |
| Funding | Multi-corporate engineering investment | Foundation-governed; mostly one small company + community |
| Bridge | JSI / TurboModules | Direct native API access (reflection; no bridge) |
| Frontend frameworks | React | TS/JS, Vue, Angular, Svelte, React |
| Plugin ecosystem | Very large | Significantly smaller |
| Cloud build | EAS Build | None equivalent; bring your own CI |
| Accessibility OOTB | RN Paper (screen-reader-validated) | [HYPOTHESIS] thinner validated surface |
| libp2p WebRTC | react-native-webrtc, widely deployed |
[HYPOTHESIS] @nativescript-community/webrtc — unverified at this stack depth |
| Hiring pool | Large | Significantly smaller |
Survival risk: RN's worst case is "Meta forces a disruptive migration" (recoverable, given Instagram/WhatsApp/Office internal dependence). NativeScript's worst case is "maintainers run out of funding and the platform stagnates" (harder to recover from) — meaningfully higher long-term survival risk despite OpenJS governance.
NativeScript's one architectural advantage: reflection-based direct native API access (e.g. androidx.work.WorkManager or AVAudioSession in TypeScript without a plugin). This matters because libp2p's mobile networking may eventually need platform-specific tuning (Wi-Fi/cellular routing, Doze coordination, background scheduling) that no Expo module covers. [HYPOTHESIS] RN's plugin ecosystem covers ~95% of MPowerUP's needs; the remaining 5% may force writing native modules anyway — exactly the work NativeScript eliminates. A real but bounded advantage.
Accessibility is the non-negotiable for this user base, and RN's story is meaningfully more mature (RN Paper, community-tested). NativeScript can build accessible apps but would rebuild that validation from scratch.
Migration cost [HYPOTHESIS] (if MPowerUP ever switched): domain logic (Yjs, libp2p, TweetNaCl, identity) survives unchanged; WatermelonDB, UI layer, and accessibility re-validation are all high-effort; ~4–6 months for a two-person team, assuming the libp2p WebRTC question resolves favourably.
Verdict: React Native remains the better default today — driven by larger contributor pool, more validated libp2p WebRTC, mature accessibility tooling, and lower platform-survival risk. NativeScript is the credible exit, not the default — it becomes right if Meta blocks MPowerUP, if MPowerUP hits Expo's native-module ceiling, if validated NativeScript libp2p-WebRTC bindings appear, or if governance becomes a funder-facing concern.
Known unknowns specific to this comparison: production parity of js-libp2p WebRTC + circuit-relay-v2 on NativeScript; nStudio's 5-year sustainability; whether NativeScript UI ecosystems reach RN Paper's accessibility baseline; relative battery performance under heavy P2P workloads.
Explicitly excluded (tech-giant-backed)¶
Per the governance filter: Flutter (Google), .NET MAUI (Microsoft), Compose Multiplatform (JetBrains), Lynx (ByteDance), Hippy (Tencent). Not evaluated because they fail the governance filter, not because they are technically unsuitable (Flutter in particular is capable; the exclusion is policy-driven).
Review trigger¶
Revisit when: Meta makes an RN roadmap decision that materially conflicts with MPowerUP (deprecation, license change); Expo Inc undergoes a governance change that breaks the budget; NativeScript demonstrates production-validated js-libp2p WebRTC + circuit-relay-v2 parity; Capacitor closes the accessibility gap; or a Meta-policy concern arises in a funder/partner conversation. Re-evaluation does not mean migration — the first action is to set this ADR to Proposed and write the successor weighing new evidence.