Install the Storefront App, add your Fleetbase and Storefront keys, and run it on iOS, Android or the web.

Storefront App Quickstart

Get the app running against your store in about 15 minutes.

Prerequisites

Tool	Version	Notes
Node.js	20	See `.nvmrc`
Yarn	3	Through Corepack (`corepack enable`); Yarn 1 won't work
Xcode	Current	With CocoaPods (installed through Bundler, `bundle install`) and an iOS Simulator
Android Studio	Current	With JDK 21, Android SDK 36 and an emulator (Android 7.0 / API 24 or later)
A Fleetbase account	—	Fleetbase Cloud or self-hosted, with the Storefront extension

Set up the React Native toolchain for your platforms first: Set up your environment.

1. Create a store and its keys

In the Console, create a store (or a Network) and add a few products — see the Storefront quickstart.

Copy the Storefront key from Storefront → Settings → API: store_… for one store, network_… for a Network. See API Settings.

Create a Fleetbase API key under Developers → API Keys.

Create a Google Maps API key with Maps SDK for Android, Maps SDK for iOS, Places API and Geocoding API enabled (and Maps JavaScript API for the web build).

2. Clone and install

git clone https://github.com/fleetbase/storefront-app.git
cd storefront-app
corepack enable
yarn install
cp .env.example .env

yarn install also applies the fixes in patches/ and links the build's brand/ folder (see Client Builds).

3. Add your keys

Fill in .env:

APP_NAME=My Store
APP_IDENTIFIER=com.mycompany.store

FLEETBASE_HOST=https://api.fleetbase.io
FLEETBASE_KEY=flb_live_…
STOREFRONT_KEY=store_…
GOOGLE_MAPS_API_KEY=AIza…

PAYMENT_GATEWAY=stripe
STRIPE_KEY=pk_test_…

On Fleetbase Cloud that's all; the app uses the hosted realtime server. Self-hosted, also set SOCKETCLUSTER_HOST and its port. Every option is in Configuration.

.env is compiled into the native apps, so changing it needs a rebuild. In development you can switch stores without one: see Switching stores in development.

4. Run it

bundle install
yarn pod:install
yarn ios

To run on a specific simulator: yarn ios --simulator="iPhone 16 Pro". To run on your iPhone, open ios/StorefrontApp.xcworkspace in Xcode, choose your team under Signing & Capabilities, pick the phone and press Run.

yarn android

Start an emulator first, or connect a phone with USB debugging on. Android builds need a google-services.json in android/app/ (see Push Notifications).

yarn web

The dev server prints the address to open. yarn web:build makes a production bundle.

The app opens on your store. Sign in with a phone number to place an order; the texted code arrives through the SMS provider set up on your Fleetbase instance.

Developing on a phone

A debug build on a phone loads its JavaScript from Metro on your computer. If changes don't reach the phone and Metro says No apps connected:

Same network. The phone and the computer must be on the same Wi-Fi. A phone on mobile data, a guest network or a VPN can't reach Metro.
Local Network permission (iOS). iOS asks whether the app may find devices on your local network the first time it reaches for Metro. If it was denied, turn the app on in Settings → Privacy & Security → Local Network, or delete it and run it again from Xcode.
Point it at Metro by hand. Shake the phone, choose Configure Bundler, and enter your computer's address and port 8081. Opening http://<computer-ip>:8081/status in the phone's browser should show packager-status:running.
The right build. A store build from TestFlight with the same bundle id replaces your debug build; the debug build shows a developer menu when you shake the phone.

Common issues

Symptom	Likely cause
A setup screen on launch	`STOREFRONT_KEY` or `FLEETBASE_KEY` missing or wrong, or `FLEETBASE_HOST` unreachable
A store with no products	No published products, or a key for a different store or environment
Network stores missing	Only active members are shown; pending and suspended stores are hidden
Blank maps on Android	`GOOGLE_MAPS_API_KEY` missing or Maps SDK for Android not enabled
Orders don't update live	Self-hosted without `SOCKETCLUSTER_HOST`, or the socket server unreachable
`yarn install` fails	Yarn 1 in use; run `corepack enable`
iOS build fails after pulling a release	Run `yarn pod:install` again

Next steps

Home Screens & Tabs: what the app opens on
Branding: your colors, fonts, icon and splash screen
Sign-in and Push Notifications
Build & Release: TestFlight, App Store and Google Play

Quickstart

On this page