Medusa Mobile

The open-source React Native storefront for Medusa v2.
Browsing, search, cart, checkout, accounts, and themes are ready on day one, so you can ship your store's iOS and Android app faster.

Quick start · Features · Themes · Roadmap · Contributing

⭐ If Medusa Mobile saves you time, please star the repo. It helps other Medusa developers find it.

• Complete shopping flow. Product listing, search, cart, promo codes, guest checkout, accounts, and order history all work against a real Medusa v2 backend.
• Pinned to Medusa. Tested with the Medusa 2.21.2 starter backend using the official JS SDK.
• Easy to brand. It ships with several themes and dark mode, built on NativeWind (Tailwind) tokens you can replace.
• Ready for real stores. It supports multiple regions, Fluent localization, strict TypeScript, CI, and unit tests.
• Plain React Native CLI. There are no proprietary services, it is MIT licensed, and you can add Expo if you prefer it.

You need a running Medusa v2 backend and a React Native environment.

git clone https://github.com/bloomsynth/medusa-mobile-react-native.git medusa-mobile
cd medusa-mobile && npm ci && cp .env.template .env   # then set your backend URL and publishable key
npm start   # in another terminal: npm run android or npm run ios

For iOS pods, emulator networking, and troubleshooting, see full setup.

• 🛍️ Product browsing with infinite scroll
• 🔎 Product search
• 👤 User authentication and profile management
• 🔍 Categories and collections
• 🛒 Cart management
• 🏃‍♂️ Guest checkout
• 📦 Order tracking
• 🎨 Beautiful UI with smooth animations
• 🌍 Multi-region support
• 🌐 Localization support
• 🌙 Dark/Light theme support
• 🎭 Multiple themes built-in
• 📱 Native performance with Reanimated

Fully customizable using the existing themes or create your own.

• React Native
• TypeScript
• Medusa JS
• React Query
• React Navigation
• NativeWind (TailwindCSS)
• React Native Reanimated

Before you begin, ensure you have:

• Node.js 22.13+ (22.x), 24.3+ (24.x), or 26+
• React Native development environment - Set Up Your Environment
• A running Medusa v2 backend server - Medusa v2 installation

1. Clone the repository:

git clone git@github.com:bloomsynth/medusa-mobile-react-native.git medusa-mobile
cd medusa-mobile

2. Install dependencies:

npm ci

3. Configure environment variables:

cp .env.template .env

Edit .env with your Medusa backend URL and publishable API key.

For the Android Studio emulator, use http://10.0.2.2:9000 (the template default). Use http://localhost:9000 for the iOS simulator or your computer’s LAN IP for a physical device. The publishable key must be linked to the sales channel containing your products. See the development guide for backend setup and troubleshooting.

npm start

For Android:

npm run android

For iOS: Install dependencies for iOS:

bundle install
cd ios
bundle exec pod install
cd ..

Run the application:

npm run ios

This project uses React Native CLI to ensure maximum flexibility for all developers. However, Expo users are more than welcome! You can easily add Expo support with a single command.

Learn more about migrating to Expo CLI

app/
├── screens/       # Screen components
├── components/    # Reusable UI components
├── data/          # Data context providers
├── styles/        # Theme and style utilities
├── utils/         # Helper functions
└── api/           # API client configuration

Start with AGENTS.md for repository instructions, the development guide for setup and validation, the architecture guide for state flow and dependency constraints, and App hooks for the shared state and theme APIs. Use Node from .nvmrc and the npm version recorded in package.json.

npm run verify

This runs lint, TypeScript, and unit tests. GitHub Actions runs the same checks on pull requests and pushes to main. Native builds and live backend checks are covered separately in the development guide.

Here are the planned features and improvements:

• 🎁 Promo code support
• 🌍 Region selector for multi-region support
• 📖 Developer Guide
• 🌐 Localization support
• 🔄 Related products suggestions
• 🔍 Product search functionality
• 💳 Stripe integration for secure payments
• 📦 cli-tool to generate a new project from this template
• 🎨 Advanced customization options
• 🔌 Plugins to extend the functionality of the app

See App hooks for the cart, region, customer, checkout, and theme hooks, with usage examples.

This project is licensed under the MIT License.