Skip to main content

RFC-0009: Mobile Strategy - React Native & Tamagui Convergence

  • Status: Implemented
  • Author: @revant.one, @kisg
  • Created: 2026-03-08
  • Updated: 2026-03-22

1. Objective​

To establish a unified, cross-platform frontend strategy for Framework M using React Native and Tamagui. This strategy leverages a single codebase that targets Web, iOS, Android, and Desktop, ensuring maximum code reuse and a consistent "zero-cliff" experience.

2. Motivation​

We are moving towards a "Total Convergence" model where the "Split-brain" logic between Web and Mobile is eliminated:

  1. Unified Design System: Tamagui all the way. We are moving away from Ant Design to use Tamagui's high-performance styling and component system for both the Web Desk and Mobile apps.
  2. Universal Responsive Container: The existing framework-m-desk package is natively responsive (FrameworkMShell) and built atop @framework-m/ui. It contains the layout logic, Auth, CRUD, and Real-time connections, meaning it can be imported directly into React Native projects. No separate "headless client" extraction is required.
  3. Native Performance: React Native utilizes platform-native components, while react-native-web + Tamagui delivers a desktop-class experience on the web.
  4. Developer Experience: Unified tooling (Vite, TypeScript, Tamagui) across the entire stack.

3. Technical Stack Selection​

We propose standardizing on React Native (0.8x+) and Tamagui for the official Framework M ecosystem.

Why Tamagui Everywhere?

  • Performance: Tamagui's compiler optimizes styles at build-time, making it one of the fastest React UI kits for both Web and Native.
  • Port & Adapter Pattern: We wrap Tamagui primitives (e.g., StyledButton = styled(View)) inside semantic React components (e.g., <Button>) in libs/framework-m-ui. This creates an abstraction layer (Adapter) that protects the rest of the monorepo from being tightly coupled to Tamagui APIs. If we ever need to swap to a different UI engine, we only swap the internal implementation of framework-m-ui components.
  • Consistency: No more mapping AntD to Tamagui. A single theme configuration, single set of tokens, and shared component primitives.
  • Vite Integration: Leveraging onestack.dev, we use Vite as a unified bundler, replacing Metro for mobile and providing a modern dev experience.

4. Architectural Strategy: The "Single Codebase" Journey​

4.1 The Universal Desk (framework-m-desk)​

The framework-m-desk package serves as the universal foundation for all applications across platforms:

  • Responsibility: JSON API communication (via Refine), Auth token management, WebSocket/NATS event handling, Metadata parsing, AND high-level layout orchestration (FrameworkMShell).
  • Agnostic Styling: Because it utilizes @framework-m/ui (which abstracts Tamagui), the UI is naturally responsive and works across Web and Mobile.
  • Direct Import: The React Native app simply imports the FrameworkMShell from framework-m-desk, sharing the exact same business logic and routing structure as the Web application.

4.2 The Universal Application​

The monorepo hosts the Universal Application (e.g., examples/universal-app) that uses:

  1. framework-m-desk for data, auth, routing, and shell layout.
  2. @framework-m/ui for shared UI primitives.
  3. Platform-specific entry points (Vite for Web, Expo for Mobile).

5. Dynamic UI & Progressive Customization​

5.1 The Universal Widget Registry​

  • The app fetches DocType metadata (JSON Schema) via /api/meta/{doctype}.
  • A Tamagui-based rendering engine (part of @framework-m/ui) generates forms and views dynamically.
  • Theming: Controlled via a single tamagui.config.ts, ensuring perfect visual parity between the ERP Desk and the Mobile app.

6. Drawbacks & Challenges​

  • Migration: The current Refine/AntD-based Desk will eventually need a transition path to the new Tamagui-based universal architecture.
  • Ecosystem: Tamagui is powerful but has a steeper learning curve than standard CSS-in-JS or component libraries like Ant Design.

7. Alternatives Considered​

  • Ant Design mapping (Superseded): Mapping AntD to Tamagui was considered but abandoned in favor of "Tamagui all the way" to reduce maintenance and design drift.
  • Flutter (Superseded): Requires a separate codebase and creates a siloed development cycle.

8. Offline & Local-First Strategy​

The mobile client and even the Web PWA will utilize SQLite (via Expo/Wasm) for a true local-first experience. By sharing the same CloudEvents protocol over NATS, clients can synchronize state with the Python backend with minimal latency and built-in conflict resolution.

9. Next Steps​

[!IMPORTANT] This RFC represents a major pivot and a commitment to Universal React + Tamagui which has now been adopted.

  • Ant Design Removal: The UI/UX team is standardizing on Tamagui via @framework-m/ui. Existing AntD components in framework-m-desk are actively being phased out in favor of the universal primitives.
  • Desktop App Validation: Verify the React Native integration path by directly referencing the FrameworkMShell component.
  • Unified Bundling: Adopting onestack.dev / Vite for mobile is a bleeding-edge move that simplifies the stack significantly but requires ongoing verification.

10. Documentation Plan​

  • Universal App Guide: A comprehensive guide on setting up the universal-app inside the monorepo.
  • Tamagui Theming for Framework M: Documentation on how to map framework design tokens to Tamagui themes.
  • Offline Sync & CloudEvents: Technical guide on utilizing the NATS backplane for mobile state synchronization.
  • Platform-Specific Ejection: Best practices for implementing native-only features vs universal features.