Open source · MIT · Flutter
Medusa Mobile for Flutter: the Flutter storefront for Medusa v2
Medusa Mobile for Flutter is an open-source Flutter storefront for Medusa v2, ported from the React Native app: browsing, search, cart, checkout, accounts and themes for iOS and Android.
Same app, written in Dart. It follows the screens and design of Medusa Mobile for React Native and talks to your own Medusa v2 backend through its Store API with a publishable key. Admin credentials and secret keys never go in the app.
iOS and Android · Tested with Medusa 2.22.1 · MIT license
Features
- Product browsing with infinite scroll, categories and collections
- Product search
- Product pages with variant selection, stock rules and related products
- Cart with quantities and promo codes
- Guest checkout: address, delivery, payment, review
- Manual payment and Stripe (Payment Sheet)
- Sign-in, registration, profile, saved addresses and order history
- Multiple regions with region prices
- Four built-in themes, each with light and dark mode
- English and Indonesian
Built with
- Flutter
- Dart
- flutter_bloc (cubits)
- go_router
- Dio
- freezed
- flutter_stripe
Status
Checked on Android against the Medusa 2.22.1 starter backend, where the checkout, account, address, settings and search flows run as end-to-end tests on a device.
Not yet checked: a real test payment through the Stripe Payment Sheet, and iOS (the project is set up for it but has not been built).
Flutter or React Native?
Both apps cover the same shopping flow against the same Medusa backend. Choose the language your team already writes.
| Flutter | React Native | |
|---|---|---|
| Language | Dart | TypeScript |
| State | flutter_bloc cubits | React Query and context |
| Styling | Theme tokens, four built-in themes | NativeWind (Tailwind) tokens |
| Requirements | Flutter 3.47+ (Dart 3.13+) | Node.js 22.22+ (22.x), 24.3+ (24.x) or 26+ |
| New project | Clone the repository | npx create-medusa-mobile |
| Source | medusa-mobile-flutter | medusa-mobile-react-native |
Quick start
You need Flutter 3.47+ (Dart 3.13+) and a running Medusa v2 backend.
git clone https://github.com/bloomsynth/medusa-mobile-flutter.git
cd medusa-mobile-flutter
cp .env.template .env # set MEDUSA_BACKEND_URL and PUBLISHABLE_API_KEY
flutter pub get
flutter run --dart-define-from-file=.envOn the Android Studio emulator the backend is http://10.0.2.2:9000 (the template default); on the iOS simulator, http://localhost:9000. Values are compiled in, so rebuild after changing .env. The README covers Stripe, physical devices and the architecture.
Differences from the React Native app
- The address form used for saved addresses is the checkout's (country picker from the region, same required fields).
- Returning to checkout resumes at Payment unless the cart already has a pending payment session.
- Order dates are shown as dates, not relative times.
Frequently asked questions
Is there a Flutter storefront for Medusa v2?
Yes. Medusa Mobile for Flutter is an open-source (MIT) Flutter storefront for Medusa v2, with browsing, search, cart, guest checkout, Stripe, accounts and order history. It is tested with Medusa 2.22.1.
How is it different from the React Native version?
It is a port of the same app, with the same screens and design, written in Dart with Flutter instead of TypeScript with React Native. A few details differ: saved addresses use the checkout address form, returning to checkout resumes at Payment, and order dates are shown as dates. The React Native version also has a project generator, npx create-medusa-mobile.
Should I use the Flutter or the React Native version?
Pick the one your team already writes. Both are MIT licensed, cover the same shopping flow and talk to your Medusa v2 backend through its Store API with a publishable key.
Does it run on iOS?
The project is set up for iOS and Android. Checked on Android against the Medusa 2.22.1 starter backend, where the checkout, account, address, settings and search flows run as end-to-end tests on a device. Not yet checked: a real test payment through the Stripe Payment Sheet, and iOS (the project is set up for it but has not been built).
Does it support Stripe?
Yes, through the Stripe Payment Sheet (flutter_stripe). Your Medusa backend registers the Stripe provider with its secret key and enables it for the region; only the Stripe publishable key goes in the app.
Is it free?
Yes. It is open source under the MIT license, so you can use and change it for your own store.