Get started with Medusa Mobile

This guide sets up Medusa Mobile, the open-source React Native storefront for Medusa v2, against your own Medusa backend and runs it on Android or iOS.

What you need

Node.js 22.22+ (22.x), 24.3+ (24.x) or 26+
A React Native development environment: see Set Up Your Environment
A running Medusa v2 backend: see the Medusa v2 installation guide. Medusa Mobile is tested with Medusa 2.22.1.

1. Clone the project and install dependencies

git clone https://github.com/bloomsynth/medusa-mobile-react-native.git medusa-mobile
cd medusa-mobile
npm ci

2. Connect it to your Medusa backend

cp .env.template .env

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

Android Studio emulator: http://10.0.2.2:9000 (the template default)
iOS simulator: http://localhost:9000
A physical device: your computer's LAN IP address

The publishable key must be linked to the sales channel that contains your products, or the store will look empty.

3. Start Metro

npm start

4. Run the app

For Android, in another terminal:

npm run android

For iOS, install the pods first, then run it:

bundle install
cd ios
bundle exec pod install
cd ..
npm run ios

Using Expo

The project uses the plain React Native CLI so that it fits any setup. If you prefer Expo, you can add it to the project: see migrating to Expo CLI.

Where the code lives

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

For backend setup, validation and troubleshooting, read the development guide; for state flow and dependencies, the architecture guide. Questions and showcases go in GitHub Discussions.