Skip to main content
Rainbow is a React Native crypto wallet app for iOS and Android. The architecture emphasizes type safety, domain organization, and custom state management patterns.

​
Core Technologies

  • React Native - Cross-platform mobile framework
  • TypeScript - Primary language for type safety
  • React Navigation - Navigation framework
  • Zustand - Foundation for custom store creators
  • MMKV - High-performance local storage
  • ethers/viem - Blockchain interactions

​
Architectural Principles

​
Type Safety First

All new code is written in TypeScript. Remaining JavaScript files are checked against an error baseline to prevent regressions. 
# Type checking
yarn lint:ts          # TypeScript files
yarn lint:js-types    # JavaScript files against baseline
yarn lint             # All linting (format + TS + JS)

​
Domain-Organized Structure

The codebase is mid-migration toward domain-organized architecture:
  • New code → src/features/ with ui/data/core layer separation
  • Legacy code → Flat top-level directories (components/, screens/, hooks/)

​
No Barrel Exports

Barrel exports (index.ts re-exports) are discouraged because they:
  • Defeat tree-shaking
  • Hide circular dependencies
  • Trigger cascading module loading
// ❌ Avoid
import { MyComponent } from '@/components';

// ✅ Prefer
import { MyComponent } from '@/components/MyComponent';
This is enforced by ESLint with a limited allowlist.

​
Type-Only Imports

Use the type annotation for type-only imports: 
import { type MyType } from './types';
import { myFunction } from './utils';

​
Architecture Layers

State Management

Custom Zustand-based stores for client and server state

Navigation

React Navigation with custom sheet coordination

Storage

MMKV-based persistent storage system

Analytics

Rudderstack-based event tracking

​
Source Layout

src/
├── features/          # New domain-organized code
│   ├── perps/         # Perpetuals trading
│   ├── polymarket/    # Prediction markets
│   ├── positions/     # Portfolio positions
│   └── rnbw-rewards/  # Rewards system
├── state/             # Zustand stores (domain-based)
├── framework/         # App-agnostic infrastructure
├── __swaps__/         # Swap feature (aliased @/swaps)
├── components/        # Legacy UI components
├── screens/           # Legacy screen components
├── hooks/             # Shared React hooks
├── helpers/           # Utility functions
└── utils/             # General utilities

​
Key Directories

New features organized by domain with ui/, data/, and core/ layers.Each feature contains:
  • components/ or ui/ - React components
  • stores/ or data/ - State management
  • hooks/ - Feature-specific hooks
  • screens/ - Screen components
  • utils/ - Feature utilities
App-agnostic infrastructure including:
  • HTTP clients
  • Safe math utilities
  • UI primitives
  • Core utilities
Zustand stores organized by domain:
  • wallets/ - Wallet management
  • swaps/ - Swap state
  • nfts/ - NFT collections
  • navigation/ - Navigation state
  • internal/ - Store creators
Swap functionality aliased as @/swaps in tsconfig. Contains swap-specific logic, UI, and state.
Separate yarn workspace for GraphQL code generation.

​
Legacy Systems

Several legacy state management systems remain in use:
These systems are being phased out. New features should use createRainbowStore or createQueryStore.

​
React Query

Located in src/react-query/ - used for server state caching. Being replaced by createQueryStore.

​
Redux

Located in src/redux/ - only used for:
  • Charts
  • Contacts
  • ENS registration
  • Gas management
  • Settings

​
Testing

yarn test                    # Run all tests
yarn jest path/to/test       # Run single test
yarn check:cycles            # Check for circular dependencies

​
Migration to External Package

The in-repo store creators (createRainbowStore, createQueryStore, createDerivedStore) are being replaced by the external stores package. The APIs are identical:
  • createRainbowStore → createBaseStore
  • createQueryStore → createQueryStore
  • createDerivedStore → createDerivedStore
Migration is mostly an import swap.

​
Next Steps

Project Structure

Detailed directory structure and organization

State Management

Learn about Rainbow’s state management system

Build docs developers (and LLMs) love

Get started for freeTalk to us