Android app for your storefront

How it works

The app is a client-only build of your project wrapped with Capacitor. Every API request goes to https://shop.example.com/api/... through the phone's native HTTP, so your storefront answers it exactly as for the website and the customer stays signed in between launches. Deploy the website first: the app works only while that domain answers.

1 Prepare the build machine

Besides Node.js 22.12 or newer, install JDK 21 and the Android SDK (Android Studio installs both). Set JAVA_HOME and ANDROID_HOME, then check them:

java -version
echo $ANDROID_HOME

2 Add Capacitor

In the root of your project, install Capacitor 8 with its App plugin, which makes the Android back button close a dialog or open the previous page, and its Filesystem and Share plugins, which save a purchased file and open it from the Android share sheet:

npm install @capacitor/core @capacitor/android @capacitor/app @capacitor/filesystem @capacitor/share
npm install -D @capacitor/cli

Create capacitor.config.json beside package.json. Choose your own app ID (a reverse domain; it can not change after the app is published) and app name. Keep native HTTP and native cookies enabled: the app reaches your storefront and keeps the session through them.

{
  "appId": "com.example.shop",
  "appName": "My shop",
  "webDir": "out",
  "plugins": {
    "CapacitorHttp": {
      "enabled": true
    },
    "CapacitorCookies": {
      "enabled": true
    }
  }
}

Projects created with the starter already have this next.config.ts. If you keep your own configuration, wrap it with androidAppConfig as shown (run npx orionplace-react init first to get orionplace/runtime/app.mjs):

import type { NextConfig } from 'next';
import { androidAppConfig } from './orionplace/runtime/app.mjs';

const nextConfig: NextConfig = androidAppConfig({
  // your options
});

export default nextConfig;

3 Build the app

Set ORIONPLACE_APP_ORIGIN to your public storefront domain over HTTPS, one of the frontends added with npx orionplace-react add frontend. With this variable next build writes a static export of the app to out/; without it, npm run build builds the website as before.

ORIONPLACE_APP_ORIGIN=https://shop.example.com npx next build
npx cap add android
npx cap sync android
cd android && ./gradlew assembleDebug

Run npx cap add android only for the first build: it creates the android/ folder. The test build is android/app/build/outputs/apk/debug/app-debug.apk. Commit the android/ folder: it holds the app icon, name and native settings.

4 Install and test

Connect a phone with USB debugging, or start an emulator in Android Studio, then install the app (npx cap run android builds, installs and opens it in one step):

adb install -r android/app/build/outputs/apk/debug/app-debug.apk

Check the main flows on the phone: sign-in with a password and with an SMS code, the cart and checkout. They send the same requests as the website.

5 Update the app

The app contains its own copy of your storefront pages. After you change pages, components or the package, run the build commands again and publish a new version: changes on the website alone do not reach installed apps. Products, prices and orders always come live from the backend.

6 Publish to Google Play

Open android/ in Android Studio, replace the icons and set the release part of android/app/build.gradle as below. applicationId must be the package name of your app in Google Play Console, which cannot change after the first upload; set the same appId in capacitor.config.json. Raise versionCode for every upload. minifyEnabled and shrinkResources turn on R8, which shrinks and optimizes the code: Play Console rates it as DEX code optimization, and Capacitor brings the keep rules for its plugins.

android {
    defaultConfig {
        applicationId "com.example.shop"
        versionCode 2
        versionName "1.0.1"
    }
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

Create a signed release bundle (Build → Generate Signed App Bundle) or build it from the command line. R8 changes the code, so install a signed release build on a phone and check the main flows again before you upload the .aab file in Google Play Console. Google Play also asks apps with accounts for account deletion inside the app and on the web: the starter's profile page has the Delete account card, so give the address of your storefront's /profile page in the Data safety form.

cd android && ./gradlew bundleRelease