# Medusa Mobile for Flutter: the Flutter storefront for Medusa v2

> Medusa Mobile for Flutter is an open-source Flutter storefront for Medusa v2, with browsing, search, cart, Stripe checkout, accounts and themes for iOS and Android.

URL: https://bloomsynth.com/medusa-mobile/flutter/
Publisher: BloomSynth (https://bloomsynth.com)

Open source · MIT · Flutter

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](https://bloomsynth.com/medusa-mobile/) 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.

[View on GitHub](https://github.com/bloomsynth/medusa-mobile-flutter) [Read the tutorial](https://codingislove.com/medusa-mobile-flutter/)

iOS and Android · Tested with Medusa 2.22.1 · MIT license

![Medusa Mobile store screens: product list, product page and cart](https://bloomsynth.com/images/medusa-mobile-cover.png)

Screens from the React Native app; the Flutter port follows the same design.

## 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](https://github.com/bloomsynth/medusa-mobile-flutter) | [medusa-mobile-react-native](https://github.com/bloomsynth/medusa-mobile-react-native) |

## Quick start

You need Flutter 3.47+ (Dart 3.13+) and a running [Medusa v2 backend](https://docs.medusajs.com/learn/installation).

```
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=.env
```

On 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](https://github.com/bloomsynth/medusa-mobile-flutter#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.

---

Medusa Mobile is free and MIT licensed: https://github.com/bloomsynth/medusa-mobile-react-native