A modern e-commerce mobile application built with React Native and Medusa. Whether you're building a React Native starter Medusa project or a production app, this provides a complete shopping experience with features like product browsing, cart management, user authentication, and order tracking.
- 🛍️ Product browsing with infinite scroll
- 👤 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 (v20 or newer)
- React Native development environment - Set Up Your Environment
- A running Medusa v2 backend server - Medusa v2 installation
- Clone the repository:
git clone git@github.com:bloomsynth/medusa-mobile-react-native.git medusa-mobile cd medusa-mobile- Install dependencies:
npm install- Configure environment variables:
cp .env.template .envEdit .env with your Medusa backend URL and publishable API key.
NOTE: Update the MEDUSA_BACKEND_URL in your .env file. If you set the URL as localhost, then the Android emulator will not be able to connect to the server. Use your local IP address instead. example: http://192.168.1.100:9000 Run ipconfig to get your local IP address.
npm startFor Android:
npm run androidFor iOS: Install dependencies for iOS:
npx pod-install iosRun 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
app/ ├── screens/ # Screen components ├── components/ # Reusable UI components ├── data/ # Data context providers ├── styles/ # Theme and style utilities ├── utils/ # Helper functions └── api/ # API client configuration Here are the planned features and improvements:
- 🎁 Promo code support
- 🌍 Region selector for multi-region support
- 📖 Developer Guide
- 🌐 Localization support
- 💳 Stripe integration for secure payments
- 🔄 Related products suggestions
- 🔍 Product search functionality
- 📦 cli-tool to generate a new project from this template
- 🎨 Advanced customization options
- 🔌 Plugins to extend the functionality of the app
The cart functionality is provided through the useCart hook, which gives you access to cart operations and state.
import { useCart } from '@data/cart-context'; function MyComponent() { const { cart, // Current cart state addToCart, // Add items to cart updateLineItem, // Update item quantity removeLineItem, // Remove item from cart applyPromoCode, // Apply discount code removePromoCode, // Remove discount code setShippingMethod // Set shipping option } = useCart(); }- Add a product to cart:
const { addToCart } = useCart(); // Quantity is required when adding items await addToCart(variantId, 1); // Add one item await addToCart(variantId, 3); // Add three items- Update item quantity:
const { updateLineItem } = useCart(); // Update to specific quantity await updateLineItem(lineItemId, 2); // Remove item by setting quantity to 0 await updateLineItem(lineItemId, 0);const { applyPromoCode, removePromoCode } = useCart(); // Apply a promotion code const success = await applyPromoCode('SUMMER2024'); // Remove a promotion code await removePromoCode('SUMMER2024');const { setShippingMethod } = useCart(); // Set shipping method await setShippingMethod(shippingMethodId);const { cart } = useCart(); // Get cart items const items = cart.items; // Get cart totals const { subtotal, tax_total, shipping_total, discount_total, total } = cart; // Check applied discounts const appliedPromotions = cart.promotions; // Get selected shipping method const currentShipping = cart.shipping_methods?.[0];The cart system handles various states and transitions:
- Cart Creation:
const { cart } = useCart(); // Cart is automatically created when needed // You don't need to explicitly create a cart- Guest to Customer Cart Transfer:
// When a guest user logs in, their existing cart is // automatically associated with their customer account // This is handled by the CartProvider and CustomerProvider import { useCustomer } from '@data/customer-context'; import { useCart } from '@data/cart-context'; function CheckoutFlow() { const { customer } = useCustomer(); const { cart } = useCart(); // Cart remains the same, only the customer_id is updated }- Cart update on region change:
import { useRegion } from '@data/region-context'; import { useCart } from '@data/cart-context'; function MyComponent() { const { region } = useRegion(); const { cart } = useCart(); // Cart automatically updates when region changes // Product prices will be updated based on the region console.log(cart.region_id); // Current region ID console.log(cart.currency_code); // Region's currency }The region functionality is provided through the useRegion hook, which handles region selection and persistence.
import { useRegion } from '@data/region-context'; function MyComponent() { const { region, // Current selected region setRegion, // Update region state } = useRegion(); }- Access current region:
const { region } = useRegion(); // Get region details (if region is loaded) const { id, name, currency_code, countries } = region || {};- Change region:
const { setRegion } = useRegion(); // Fetch region data first const { region: newRegion } = await apiClient.store.region.retrieve(regionId); // Update region setRegion(newRegion); // This will: // - Persist region selection // - Update cart region automatically // - Trigger price recalculationsThe app provides a built-in region selector modal:
import { useNavigation } from '@react-navigation/native'; function MyComponent() { const navigation = useNavigation(); // Open region selector modal const openRegionSelect = () => { navigation.navigate('RegionSelect'); }; }The app provides a dedicated hook for accessing region countries:
import { useCountries } from '@data/region-context'; function AddressForm() { const countries = useCountries(); // Format countries for picker/selector const countryOptions = countries?.map(country => ({ label: country.display_name, value: country.iso_2 })); }Region selection is automatically persisted using AsyncStorage:
- On first load, defaults to the first available region
- On subsequent loads, restores the previously selected region
- Region ID is stored under the 'region_id' key
The customer functionality is provided through the useCustomer hook, which handles authentication and customer data management.
import { useCustomer } from '@data/customer-context'; function MyComponent() { const { customer, // Current customer data login, // Login with email/password logout, // Logout current customer register, // Register new customer refreshCustomer, // Refresh customer data updateCustomer // Update customer details } = useCustomer(); }- Login:
const { login } = useCustomer(); try { await login(email, password); // On successful login: // - JWT token is stored in AsyncStorage // - Customer data is fetched // - Cart is associated with customer } catch (error) { // Handle login error }- Register new customer:
const { register } = useCustomer(); try { await register( email, password, firstName, lastName ); // Registration automatically logs in the customer } catch (error) { // Handle registration error }- Logout:
const { logout } = useCustomer(); await logout(); // This will: // - Clear the stored JWT token // - Reset customer data // - Reset cart- Access customer information:
import { useLoggedIn } from '@data/hooks'; function MyComponent() { const { customer } = useCustomer(); const isLoggedIn = useLoggedIn(); // Access customer details const { email, first_name, last_name, phone, billing_address, shipping_addresses } = customer || {}; }- Update customer details:
const { updateCustomer } = useCustomer(); // Update customer information await updateCustomer({ first_name: "John", last_name: "Doe", phone: "+1234567890" });- Refresh customer data:
const { refreshCustomer } = useCustomer(); // Fetch latest customer data from server await refreshCustomer();The customer session is automatically managed:
- JWT token is stored in AsyncStorage under 'auth_token'
- Session is restored on app launch
- Token is automatically attached to API requests
- Session is cleared on logout
The app includes a flexible theming system with built-in light/dark mode support and multiple color schemes.
import { useColors, useTheme, useThemeName, useColorScheme } from '@styles/hooks'; function MyComponent() { const colors = useColors(); // Get current theme colors const themeName = useThemeName(); // Get current theme name const { colorScheme } = useColorScheme(); // Get 'light' or 'dark' // Access theme colors const { primary, // Brand/accent color background, // Main background backgroundSecondary,// Secondary/card background content, // Main text color contentSecondary // Secondary text color } = colors; }// In app.tsx, set your preferred theme name in ThemeProvider <ThemeProvider name="default"> {/* ... other providers */} </ThemeProvider>Available theme names:
- "default" (Purple accent)
- "vintage" (Warm red accent)
- "funky" (Teal accent)
- "eco" (Green accent)
import { useTheme } from '@styles/hooks'; function ThemeSwitcher() { const { setThemeName } = useTheme(); // Switch to a different theme const switchTheme = (name: string) => { setThemeName(name); // 'default' | 'vintage' | 'funky' | 'eco' }; }The theme system automatically responds to system dark mode changes through NativeWind's useColorScheme hook. Each theme includes both light and dark variants that are automatically applied based on the system setting.
The app uses NativeWind (TailwindCSS) for styling. Theme colors are available as Tailwind classes:
function ThemedButton() { return ( <TouchableOpacity className="bg-primary"> // Theme primary color <Text className="text-content font-bold"> // Theme content color Click Me </Text> </TouchableOpacity> ); }The app provides additional hooks for common functionality:
import { useProductQuantity, useVariantQuantity, useCartQuantity, useCurrentCheckoutStep, useActivePaymentSession, useLoggedIn, useCountries } from '@data/hooks'; // Get quantity of a specific product in cart const quantity = useProductQuantity(productId); // Get quantity of a specific variant in cart const variantQuantity = useVariantQuantity(variantId); // Get total number of items in cart const cartQuantity = useCartQuantity(); // Get current checkout step const checkoutStep = useCurrentCheckoutStep(); // Returns: 'address' | 'delivery' | 'payment' | 'review' // Get active payment session in checkout const paymentSession = useActivePaymentSession(); // Check if user is logged in const isLoggedIn = useLoggedIn(); // Get formatted list of countries for current region const countries = useCountries(); // Returns: Array<{ label: string, value: string }>This project is licensed under the MIT License.

