ExpoReact
Home › Technical Guides › Runtime Architecture
Runtime Architecture

Designing a Unified Cross-Platform Runtime for iOS, Android, and Web

Map shared TypeScript primitives cleanly onto native UIKit, Android Views, and web DOM targets with deterministic boundaries.

Core Layers of a Single-Codebase Runtime

A unified cross-platform runtime separates application logic written in TypeScript from platform-specific rendering and device drivers. At the top layer, shared components such as View, Text, and navigation containers describe interface intent declaratively rather than invoking imperative UIKit or Android View APIs directly. Underneath, a synchronous host interface connects JavaScript memory to native C++, Swift, or Kotlin objects without serializing every call into JSON strings.

Keeping business logic, domain validation, and state transitions inside the shared layer prevents feature drift between mobile and browser releases. Meanwhile, keeping a well-typed adapter boundary for platform capabilities ensures that each target respects operating system conventions such as safe-area insets, hardware back navigation, and browser history stacks without duplicating core product workflows across separate repositories.

Synchronous Host Bindings vs. Asynchronous Bridges

Legacy cross-platform frameworks relied on asynchronous message queues that batched serialized JSON payloads between the JavaScript thread and native UI threads. Under heavy scroll events or rapid gesture updates, serialization overhead created visible frame drops and stale layout state. Modern unified runtimes replace serialized queues with direct host object references, enabling synchronous property reads when layout measurements are needed immediately.

Synchronous bindings do not eliminate the need for careful thread budgeting across mobile devices. Long-running encryption, image decoding, or database queries must still execute on background worker queues so neither the JavaScript event loop nor the native main thread blocks user input, ensuring smooth frame delivery across both older phones and modern desktop browsers.

Organizing Shared vs. Platform-Specific Extensions

Clean repository boundaries keep platform forks predictable as codebases scale. Most screens, form validators, and API clients remain in standard .tsx files shared across iOS, Android, and web. Only modules that wrap distinct hardware semantics—such as file pickers, biometric prompts, or share sheets—split into .ios.ts, .android.ts, and .web.ts implementations behind a single exported TypeScript interface.

Enforcing identical return shapes and error codes across all three file extensions allows product engineers to write unit and integration tests against one unified contract while platform specialists optimize native internals independently. Whenever a mobile sensor lacks browser support, the web adapter exposes an explicit capability flag so callers degrade gracefully.

Versioning the Native Container and JavaScript Bundle

Every unified app ships two coupled artifacts: a compiled native binary distributed through app stores and a JavaScript bundle loaded at startup. If a JavaScript bundle expects a native hook signature that older installed binaries lack, the application will throw an immediate runtime error on invocation and potentially crash during user onboarding.

Teams prevent binary-interface mismatches by deriving a deterministic runtime version hash from native dependency manifests and module signatures. Update servers match incoming client headers against that runtime key so JavaScript bundles only load onto compatible native containers while older binaries receive store-upgrade prompts.

Cross-Platform Runtime Layer Tradeoffs

Architecture LayerCommunication ModelPrimary BottleneckMitigation Strategy
Legacy JSON BridgeAsync batched queueSerialization & thread hopsBatch calls or use host bindings
Host Bindings (JSI)Synchronous C++ refsHeavy work on JS loopOffload I/O to worker threads
Shadow Tree LayoutCross-thread Yoga calcDeep flex recalculationsFlatten view trees and memoize
Web DOM AdapterReact DOM + static CSSBundle & style runtime costExtract CSS and split routes
Native Module RegistryLazy platform adaptersEager cold-start loadingDefer non-critical modules

Reference comparison of common architectural tradeoffs across unified mobile and web runtimes.

Worked Illustration: Budgeting Module Sharing Across Targets

Illustrative scenario: A team structures a 120-module application across iOS, Android, and web to minimize maintenance while isolating hardware APIs.

  1. Step 1 (Illustrative audit): Classify 120 modules into domain logic (48), UI screens (54), and hardware adapters (18).
  2. Step 2 (Illustrative sharing): Keep all 48 logic modules and 50 UI screens in shared .tsx files (98 unified modules, or 81.7%).
  3. Step 3 (Illustrative isolation): Split 4 platform shells and 18 hardware adapters into .ios.ts, .android.ts, and .web.ts files.
  4. Step 4 (Illustrative check): Run contract tests across all three target adapters in CI before allowing merges.

Engineering Takeaway: Over 80% of modules stay unified while the 18 hardware adapters remain cleanly swappable per target.

Unified Runtime Architecture Checklist

  • Define strict TypeScript interfaces for every native and web adapter module.
  • Defer non-critical native module initialization until after first screen paint.
  • Flatten redundant wrapper Views where a single container suffices.
  • Expose typed capability checks and graceful fallbacks on the web target.
  • Derive a deterministic runtime version key from native dependency manifests.
  • Verify navigation restoration across hardware back buttons and browser history.

Frequently Asked Questions

Can a single TypeScript codebase match native iOS and Android ergonomics?

Yes, when shared logic renders genuine native views on mobile and uses platform file extensions for navigation headers, haptics, and pickers.

Why do unified runtimes prefer synchronous host bindings over JSON bridges?

Direct host bindings avoid JSON serialization and asynchronous queue hops, improving gesture responsiveness and synchronous layout measurements.

How should teams handle features that only exist on mobile devices?

Expose an explicit isAvailable capability check on the shared adapter interface and provide clean web fallbacks such as standard file inputs.

What causes most runtime crashes after shipping a JavaScript bundle?

Runtime version mismatch—shipping JS code that calls a newly added native method to users running an older store binary.

Primary References & Standards

  • React Native Architecture Documentation — New Architecture, JSI, and Fabric Renderer
  • ECMA-262 ECMAScript Language Specification — Ecma International
  • Apple Human Interface Guidelines & Android Developers Core App Quality Guidelines

Related Technical Guides