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 · 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.
- One command to start.
npx create-medusa-mobile my-storecreates 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.
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 iosThe 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.
- 🛍️ 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.22+ (22.x), 24.3+ (24.x), or 26+, and Git
- React Native development environment - Set Up Your Environment
- A running Medusa v2 backend server - Medusa v2 installation
npx create-medusa-mobile my-store
cd my-storeThe 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 .envnpm startFor Android:
npm run androidFor iOS: Install dependencies for iOS:
bundle install
cd ios
bundle exec pod install
cd ..Run the application:
npm run iosThis 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
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.
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 verifyThis 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.
If you use Medusa Mobile, ⭐ star it on GitHub and share what you built.
