Clone the Storefront App, install dependencies, configure your Fleetbase keys, and run it in iOS, Android, or web.

Storefront App Quickstart

Get the Storefront App running locally against your Fleetbase backend in about 15 minutes.

Prerequisites

Tool	Version	Notes
Node.js	≥20	See `.nvmrc`
Yarn	3.6.4	Installed via Corepack — do not use Yarn 1
React Native CLI environment	—	Set up your dev environment for iOS (Xcode + Watchman) and Android (Android Studio + JDK 17)
Ruby + Bundler	3.x	iOS pods are installed via `bundle exec pod install`
A Fleetbase account	—	Self-hosted or fleetbase.io

You will also need:

A Fleetbase API secret key — Console → Developers
A Storefront key — Console → Storefront → Settings → API (store_* for one store; network_* for a network)
A Google Maps API key with Maps SDK for iOS, Maps SDK for Android, and (if running web) Maps JavaScript API enabled
A Stripe publishable key if you plan to use Stripe

1. Clone and Install

git clone git@github.com:fleetbase/storefront-app.git
cd storefront-app

corepack enable
corepack prepare yarn@3.6.4 --activate

yarn
bundle install

The postinstall step automatically applies the entries in patches/ via patch-package.

2. Install iOS Pods

cd ios && bundle exec pod install && cd ..

The pod install runs with the React Native New Architecture enabled (RCT_NEW_ARCH_ENABLED=1). All native modules in this project are New Arch compatible.

3. Configure `.env`

Create a .env file at the project root with at minimum:

APP_NAME=Storefront
APP_IDENTIFIER=com.yourcompany.storefront

# Your Fleetbase backend
FLEETBASE_HOST=https://your-fleetbase.example.com
FLEETBASE_KEY=flb_live_...
STOREFRONT_KEY=$store.your_store_key

# Real-time order updates
SOCKETCLUSTER_HOST=socket.your-fleetbase.example.com
SOCKETCLUSTER_PORT=8000
SOCKETCLUSTER_SECURE=true

# Maps & payments
GOOGLE_MAPS_API_KEY=AIza...
STRIPE_KEY=pk_test_...
PAYMENT_GATEWAY=stripe

The bundled .env.example lists GOOGLE_MAPS_KEY, but the runtime reads GOOGLE_MAPS_API_KEY. Use GOOGLE_MAPS_API_KEY.

The full set of supported environment variables — theming, tabs, payments, social login, locale labels, etc. — is documented in Configuration.

4. Run the App

iOS Simulator

yarn ios

This starts Metro and launches the iOS simulator. To target a specific device:

npx react-native run-ios --simulator="iPhone 15 Pro"

Android Emulator

yarn android

Make sure an emulator is already running (emulator -list-avds, then emulator -avd <name>) or a physical device is connected with USB debugging enabled.

Web

yarn web

Webpack dev server boots and serves the app at the URL it logs. The web target uses react-native-web with build-time aliasing for native-only modules.

The web build is functional for development and demos. There is no production-optimized webpack configuration in the repo — if you intend to ship the web app to customers, plan to add one.

Once the app launches:

The boot screen calls your Fleetbase backend using STOREFRONT_KEY.
The app discovers the configured store (or network) and renders its catalog.
Customer accounts are created via the Phone + SMS flow by default, or via Apple/Google/Facebook if you've enabled those (see Integrations).

Common Issues

Symptom	Likely cause
`Unauthorized` on launch	`STOREFRONT_KEY` or `FLEETBASE_KEY` is missing or wrong, or `FLEETBASE_HOST` is unreachable
Empty store list / blank catalog	Your store has no published products, or the wrong Storefront key for your environment
Maps not rendering	`GOOGLE_MAPS_API_KEY` missing, or the relevant platform SDK is not enabled in Google Cloud
Real-time updates stuck	`SOCKETCLUSTER_HOST`/`PORT` not set, or the Fleetbase socket service isn't reachable
Yarn install fails	Using Yarn 1 — switch to Yarn 3 via Corepack
iOS build fails on first run	Run `yarn pod:install` (or `cd ios && bundle exec pod install`) again after a clean checkout

Next Steps

Configuration — full env-var and config reference
Theming — colors, fonts, branding assets
Integrations — payment gateways, social login, push notifications
Build & Release — release builds for App Store, Play Store, and web

Quickstart

On this page