Skip to content

README.md

Latest commit

 

History

History
226 lines (159 loc) · 6.04 KB

README.md

File metadata and controls

226 lines (159 loc) · 6.04 KB

Welcome to POS Sample app

Prerequisites

Before you begin, make sure you have set up your React Native development environment. This includes installing Node, Android Studio (for Android), and Xcode (for iOS on macOS).

Follow the official React Native documentation to set up your environment:

Get started

  1. Install dependencies

    npm install

  2. Set up environment variables

    Create a .env file using the example template:

    cp .env.example .env

    Update the .env file with your configuration values.

  3. Create native folders

    npm run prebuild

    This will automatically set up the required files for development.

  4. Start the app

    npm run android
    npm run ios
    npm run web

Production Releases

For production Android releases, you'll need the actual secrets.properties file and wc_rn_upload.keystore. Get these from the mobile team or 1Password.

Required file locations:

  • Place secrets.properties in the android/ directory
  • Place wc_rn_upload.keystore in the android/app/ directory
android/
├── secrets.properties          ← Place here
└── app/
    └── wc_rn_upload.keystore  ← Place here

Build the release APK:

npm run android:build

The release APK will be generated at android/app/build/outputs/apk/release/app-release.apk

Install on a device via USB:

Note: Make sure USB debugging is enabled on your Android device. Go to Settings → About phone → Tap "Build number" 7 times → Developer options → Enable "USB debugging".

  1. Connect your device via USB and get its device ID:

    adb devices

    Example output: V510BAC07114B000171

  2. Build the release APK:

    npm run android:build

  3. Install the APK on your device (replace with your device ID):

    adb -s V510BAC07114B000171 install android/app/build/outputs/apk/release/app-release.apk

⚠️ Security Note: Never commit secrets.properties or keystore files to version control.

OTA Updates

The app supports Over-The-Air (OTA) updates via EAS Update. This lets you push JavaScript-only changes to devices without rebuilding and redistributing the native app.

Channels

  • production — updates for production builds (Firebase/TestFlight releases)

Publishing an Update

Via GitHub Actions (recommended):

  1. Go to GitHub Actions → "OTA Update Mobile POS"
  2. Optionally add a message describing the changes
  3. Run the workflow

The workflow will automatically verify that no native changes are included. If native changes are detected, the workflow fails with a clear error — you must create a new native release first.

Via CLI:

cd dapps/pos-app
eas update --channel production --message "fix: description of changes"

Verifying an Update

Open Settings in the app — the version text shows the current OTA update ID and channel.

Limitations

OTA updates only deliver JavaScript bundle changes. The following require a full native release:

  • Adding/removing native modules or permissions
  • Changing app.json native configuration (iOS entitlements, Android permissions, etc.)
  • Upgrading the Expo SDK or React Native version

Rollback

eas update:rollback --channel production

If the app crashes after an OTA update, expo-updates automatically falls back to the previous working bundle.

Creating Custom Variants

To create a branded variant for a specific client:

  1. Create a new branch

    git checkout -b variant/<client-name>

  2. Add the variant logo

    • Add the client's logo to assets/images/variants/<client-name>_brand.png
    • Requirements: PNG format

  3. Add the printer logo in constants/printer-logos.ts

  4. Define the variant in constants/variants.ts

    • Import the printer logo at the top of the file: 
      import {
  // ... existing imports ...
  <CLIENT_NAME>_LOGO_BASE64,
} from "./printer-logos";
    • Add the variant name to the VariantName type: 
      export type VariantName =
  | "default"
  | "solflare"
  | "binance"
  | "phantom"
  | "solana"
  | "<client-name>";
    • Add the variant configuration to the Variants object: 
      <client-name>: {
  name: "<Client Name>",
  brandLogo: require("@/assets/images/variants/<client-name>_brand.png"),
  printerLogo: <CLIENT_NAME>_LOGO_BASE64,
  defaultTheme: "light", // or "dark"
  colors: {
    light: {
      "icon-accent-primary": "#HEXCOLOR",
      "bg-accent-primary": "#HEXCOLOR",
      "bg-payment-success": "#HEXCOLOR",
      "text-payment-success": "#HEXCOLOR",
      "border-payment-success": "#HEXCOLOR",
    },
    dark: {
      // Same color keys as light theme
    },
  },
},

  5. Update Android version code in app.json

    • Increment expo.android.versionCode

  6. Commit, push, and create a release tag (Devin only)

    git add .
git commit -m "feat: add <client-name> variant"
git push origin variant/<client-name>
git tag variant-<client-name>
git push origin variant-<client-name>

    The tag will trigger the release workflow automatically.

  7. Verify the release

    • Check the build status and Firebase link in the #system-releases-react-native Slack channel

Manual release: If you need to trigger the release manually instead of using a tag, go to GitHub Actions and run the release-android-mobilepos workflow.