Skip to content

About

Open-source React Native storefront for Medusa v2: browsing, search, cart, checkout, accounts and themes for iOS and Android

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

98 stars

Watchers

5 watching

Forks

Latest commit

 

History

130 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

GitHub stars Verify License: MIT Tested with Medusa 2.22.1 Platforms TypeScript PRs welcome

Quick start · Features · Themes · Roadmap · Flutter version · Contributing

Building with Flutter? See Medusa Mobile for Flutter.

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

Medusa Mobile screens

💡 Why Medusa Mobile?

  • One command to start. npx create-medusa-mobile my-store creates your store's app with its own name, bundle ID, and backend settings.
  • 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.22.1 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.

⚡ Quick start

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

npx create-medusa-mobile my-store
cd my-store
npm start   # in another terminal: npm run android or npm run ios

The CLI asks for your app name, bundle ID, backend URL, and publishable key. It then renames the Android and iOS projects, writes .env, installs dependencies, and makes the first Git commit. For iOS pods, emulator networking, and troubleshooting, see full setup.

✨ Features

  • 🛍️ 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

🎨 Themes

Multiple themes

Fully customizable using the existing themes or create your own.

🛠️ Tech Stack

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

📋 Prerequisites

Before you begin, ensure you have:

🚀 Getting Started with React Native Medusa

Step 1: Create your project

npx create-medusa-mobile my-store
cd my-store

The CLI prompts for the app name, display name, bundle ID, Medusa backend URL, and publishable API key. It copies this template, renames the Android and iOS projects, writes .env, runs npm ci, and makes an initial Git commit. Pass --yes and options such as --bundle-id to skip the prompts; see the CLI guide for every option.

For the backend URL, use http://10.0.2.2:9000 for the Android Studio emulator (the default), 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. You can change both later in .env. See the development guide for backend setup and troubleshooting.

To work on Medusa Mobile itself, for example to contribute, clone the repository instead:

git clone git@github.com:bloomsynth/medusa-mobile-react-native.git medusa-mobile
cd medusa-mobile
npm ci
cp .env.template .env

Step 2: Start Metro Server

npm start

Step 3: Run the Application

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

📱 Expo Usage

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

🐦 Flutter version

Medusa Mobile for Flutter is a port of this app to Flutter, with the same screens and design: browsing, search, cart, checkout with manual payment and Stripe, accounts, regions, and themes. Use it if your team works in Dart. The Medusa Mobile site covers both apps.

📁 Project Structure

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

Development and AI agents

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.

📍 Roadmap

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

📖 Developer Guide

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

🛡️ License

This project is licensed under the MIT License.


If you use Medusa Mobile, ⭐ star it on GitHub and share what you built.

About

Open-source React Native storefront for Medusa v2: browsing, search, cart, checkout, accounts and themes for iOS and Android

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

98 stars

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages