DEV Community: Kigbu Amekalo

Building a React Native NPM Library for Moniepoint POS SDK - Transforming Revenue Collection in Nigeria

Kigbu Amekalo — Fri, 31 Oct 2025 07:45:16 +0000

Building a React Native NPM Library for Moniepoint POS SDK: A Journey from Field Agents to Open Source

🎯 The Problem We Solved

At Flopay, we're revolutionizing revenue collection and remittance across Nigeria. As a product by I-Tech Platform Limited, we help government bodies, schools, churches, and enterprises streamline their revenue management — from informal market levies to formal tax remittances.

Our field agents use the Flopay Agent Mobile App to process payments on behalf of organizations. They collect everything from school fees to government taxes, serving millions of payers across multiple states including Adamawa, Yobe, Borno, and Taraba.

But we faced a critical challenge: How do we enable seamless card payments and provide instant printed receipts as proof of payment in the field?

Enter Moniepoint — Africa's fastest-growing financial institution and Nigeria's largest merchant acquirer, processing $17 billion monthly for over 10 million business and individual accounts.

💡 Why Moniepoint POS?

Moniepoint powers most of Nigeria's Point of Sale (POS) transactions. Their PaaP SDK (Payment as a Platform) allows developers to deploy custom applications directly to Moniepoint POS terminals, enabling:

✅ Card Payment Processing — Accept debit/credit cards seamlessly
✅ Receipt Printing — Print branded receipts with logos, QR codes, and custom formatting
✅ POS Transfer Acceptance — Handle bank transfers at the terminal
✅ Terminal Data Access — Get device info for audit trails
✅ NFC Support — Read ID cards and loyalty cards

This was perfect for our use case: Field agents collecting revenue with instant payment processing and receipt printing.

🏗️ The Challenge: Making It Reusable

Initially, we integrated the Moniepoint PaaP SDK directly into our Flopay Agent App (written in React Native). The integration worked beautifully, but we realized:

"Other businesses in Nigeria face the same challenge. What if we could package this into a reusable npm library?"

We decided to create react-native-moniepoint-pos-sdk — an open-source npm package that any React Native developer can install and use to deploy their apps to Moniepoint POS terminals.

📦 Introducing `react-native-moniepoint-pos-sdk`

Installation

npm install react-native-moniepoint-pos-sdk

Quick Example

import MoniepointPosSdk, {
  ReceiptItemType,
} from 'react-native-moniepoint-pos-sdk';

// 1️⃣ Process a card payment (amount in Naira)
const handlePayment = async () => {
  try {
    const result = await MoniepointPosSdk.makeCardPayment('5000'); // ₦5,000
    console.log('Payment approved:', result);
  } catch (error) {
    console.error('Payment failed:', error.message);
  }
};

// 2️⃣ Print a branded receipt with logo and QR code
const handlePrintReceipt = async () => {
  const receipt = [
    {type: ReceiptItemType.IMAGE, value: 'base64EncodedLogo...'},
    {type: ReceiptItemType.LABEL, value: 'FLOPAY AGENT'},
    {type: ReceiptItemType.TITLE, value: 'PAYMENT RECEIPT'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Amount:', value: '₦5,000.00'},
    {
      type: ReceiptItemType.KEY_VALUE,
      key: 'Date:',
      value: new Date().toLocaleDateString(),
    },
    {type: ReceiptItemType.KEY_VALUE, key: 'Status:', value: 'PAID'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.QR, value: 'https://flopay.net/receipt/TXN123456'},
    {type: ReceiptItemType.LABEL, value: 'Thank you for your payment'},
  ];

  await MoniepointPosSdk.printReceipt(receipt);
};

// 3️⃣ Get terminal information (for audit trails)
const getTerminalInfo = async () => {
  const info = await MoniepointPosSdk.getTerminalData();
  console.log('Terminal ID:', info.terminalId);
  console.log('Serial No:', info.serialNo);
};

🚀 Real-World Use Cases in Nigeria

Based on Moniepoint's official documentation and our experience with Flopay, here are powerful use cases for this SDK:

1. 🏛️ Government Revenue Collection (Our Use Case!)

Scenario: Field agents collect market levies, property taxes, or license fees.

Implementation:

// Accept card payment for government levy
const collectTax = async (payerName, amount, levyType) => {
  try {
    const result = await MoniepointPosSdk.makeCardPayment(amount);

    // Print official government receipt
    const receipt = [
      {type: ReceiptItemType.LABEL, value: 'TARABA STATE GOVERNMENT'},
      {type: ReceiptItemType.TITLE, value: 'TAX RECEIPT'},
      {type: ReceiptItemType.SEPARATOR},
      {type: ReceiptItemType.KEY_VALUE, key: 'Payer Name', value: payerName},
      {type: ReceiptItemType.KEY_VALUE, key: 'Levy Type', value: levyType},
      {type: ReceiptItemType.KEY_VALUE, key: 'Amount', value: `₦${amount}`},
      {type: ReceiptItemType.KEY_VALUE, key: 'Txn Ref', value: result},
      {type: ReceiptItemType.SEPARATOR},
      {
        type: ReceiptItemType.LABEL,
        value: 'Authorized Signature: _____________',
      },
    ];

    await MoniepointPosSdk.printReceipt(receipt);
  } catch (error) {
    console.error('Tax collection failed:', error);
  }
};

Business Value:

✅ Transparent audit trail with transaction references
✅ Instant printed proof of payment reduces disputes
✅ Digital records improve compliance

2. 🏫 School Fees Collection

Scenario: Schools accept tuition payments directly on campus.

const collectSchoolFees = async (studentName, studentClass, term, amount) => {
  const result = await MoniepointPosSdk.makeCardPayment(amount);

  const receipt = [
    {type: ReceiptItemType.LABEL, value: 'SUNRISE COLLEGE'},
    {type: ReceiptItemType.TITLE, value: 'SCHOOL FEES RECEIPT'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Student', value: studentName},
    {type: ReceiptItemType.KEY_VALUE, key: 'Class', value: studentClass},
    {type: ReceiptItemType.KEY_VALUE, key: 'Term', value: term},
    {type: ReceiptItemType.KEY_VALUE, key: 'Amount', value: `₦${amount}`},
    {type: ReceiptItemType.LABEL, value: 'Thank you for your payment'},
  ];

  await MoniepointPosSdk.printReceipt(receipt);
};

3. ⛪ Church Revenue Management

Scenario: Digitize tithes, offerings, and event registrations across branches.

const recordOffering = async (memberName, offeringType, amount) => {
  const result = await MoniepointPosSdk.makeCardPayment(amount);

  const receipt = [
    {type: ReceiptItemType.LABEL, value: 'CHURCH OF CHRIST IN NATIONS'},
    {type: ReceiptItemType.TITLE, value: 'OFFERING RECEIPT'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Member', value: memberName},
    {type: ReceiptItemType.KEY_VALUE, key: 'Type', value: offeringType},
    {type: ReceiptItemType.KEY_VALUE, key: 'Amount', value: `₦${amount}`},
    {type: ReceiptItemType.LABEL, value: 'God bless you!'},
  ];

  await MoniepointPosSdk.printReceipt(receipt);
};

4. 🏥 Healthcare & Pharmacy Billing

Scenario: Hospitals and clinics process patient payments with detailed receipts.

const processPatientBilling = async (patientName, services, totalAmount) => {
  const result = await MoniepointPosSdk.makeCardPayment(totalAmount);

  const receipt = [
    {type: ReceiptItemType.IMAGE, value: hospitalLogoBase64},
    {type: ReceiptItemType.LABEL, value: 'Sunrise Medical Center'},
    {type: ReceiptItemType.TITLE, value: 'Patient Billing Receipt'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Patient', value: patientName},
    ...services.map(service => ({
      type: ReceiptItemType.KEY_VALUE,
      key: service.name,
      value: `₦${service.cost}`,
    })),
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Total', value: `₦${totalAmount}`},
    {
      type: ReceiptItemType.QR,
      value: `https://hospital.com/receipt/${patientId}`,
    },
  ];

  await MoniepointPosSdk.printReceipt(receipt);
};

5. 🛒 Retail POS with Inventory Sync

Scenario: Small businesses process checkout with card payments and printed receipts.

const processCheckout = async (items, total) => {
  const result = await MoniepointPosSdk.makeCardPayment(total);

  const receipt = [
    {type: ReceiptItemType.IMAGE, value: storeLogoBase64},
    {type: ReceiptItemType.LABEL, value: 'YOUR STORE NAME'},
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.TITLE, value: 'SALES RECEIPT'},
    ...items.map(item => ({
      type: ReceiptItemType.KEY_VALUE,
      key: item.name,
      value: `₦${item.price}`,
    })),
    {type: ReceiptItemType.SEPARATOR},
    {type: ReceiptItemType.KEY_VALUE, key: 'Total', value: `₦${total}`},
    {type: ReceiptItemType.LABEL, value: 'Thank you for shopping with us!'},
  ];

  await MoniepointPosSdk.printReceipt(receipt);
};

🔧 How We Built It

1️⃣ Native Android Module (Kotlin)

We bridged the Moniepoint PaaP SDK to React Native using Kotlin:

class MoniepointPosModule(
    private val reactContext: ReactApplicationContext,
    private val moniepointPaapSdk: MoniepointPaapSdk
) : ReactContextBaseJavaModule(reactContext) {

    @ReactMethod
    fun makeCardPayment(amount: String, promise: Promise) {
        try {
            val amountInKobo = (amount.toDouble() * 100).toLong()
            moniepointPaapSdk.cardPaymentService.makeCardPayment(amountInKobo) { response ->
                if (response.responseCode == "00") {
                    promise.resolve(response.reference)
                } else {
                    promise.reject("PAYMENT_FAILED", response.message)
                }
            }
        } catch (e: Exception) {
            promise.reject("PAYMENT_ERROR", e.message)
        }
    }

    @ReactMethod
    fun printReceipt(items: ReadableArray, promise: Promise) {
        try {
            val receiptItems = parseReceiptItems(items)
            moniepointPaapSdk.printerService.print(receiptItems)
            promise.resolve("Receipt printed successfully")
        } catch (e: Exception) {
            promise.reject("PRINT_ERROR", e.message)
        }
    }
}

2️⃣ JavaScript Interface

We created a clean JavaScript API with TypeScript definitions:

export declare class MoniepointPosSdk {
  static makeCardPayment(amount: string | number): Promise<string>;
  static printReceipt(items: ReceiptItem[]): Promise<void>;
  static getTerminalData(): Promise<TerminalData>;
  static acceptPosTransfer(reference: string): Promise<void>;
}

export type ReceiptItemType =
  | 'IMAGE'
  | 'LABEL'
  | 'TITLE'
  | 'KEY_VALUE'
  | 'SEPARATOR'
  | 'SPACING'
  | 'QR';

3️⃣ Secure Credential Management

Moniepoint requires Maven repository credentials. We made this flexible:

Option A: local.properties (Development)

moniepointRepoUrl=https://open-repository.moniepoint.com/repository/public
moniepointUsername=your_username
moniepointPassword=your_password
moniepointSdkVersion=1.0.10

Option B: Environment Variables (CI/CD)

export MONIEPOINT_REPO_URL=https://...
export MONIEPOINT_USERNAME=...
export MONIEPOINT_PASSWORD=...

The SDK's build.gradle reads from both sources:

def localProperties = new Properties()
def localPropertiesFile = file("../../local.properties")
if (localPropertiesFile.exists()) {
    localPropertiesFile.withInputStream { stream -> localProperties.load(stream) }
}

def repoUrl = localProperties.getProperty("moniepointRepoUrl")
    ?: project.findProperty("moniepointRepoUrl")
    ?: System.getenv("MONIEPOINT_REPO_URL")

📊 Business Impact for Flopay

Since deploying our app to Moniepoint POS terminals, we've achieved:

✅ ₦36 billion in revenue processed
✅ Over 1.2 million student registrations processed
✅ 100,000+ payers enumerated across multiple states
✅ Zero disputes over payment receipts (printed proof eliminates conflicts)
✅ Faster collections — agents no longer need separate card readers

Our field agents now carry a single Moniepoint POS terminal that runs the Flopay Agent App, processes card payments, and prints official receipts — all in one device.

🇳🇬 Why This Matters for Nigerian Businesses

Nigeria's economy thrives on informal sector transactions. According to Moniepoint's 2024 Informal Economy Report, millions of businesses operate outside traditional banking infrastructure.

The react-native-moniepoint-pos-sdk democratizes access to:

Digital Payment Acceptance — Move from cash-only to card payments
Financial Inclusion — Serve customers in remote areas
Trust Through Receipts — Printed receipts build credibility
Business Growth — Access to Moniepoint's 10M+ user network

Whether you're building solutions for:

🏛️ Government revenue collection
🏫 School fee management
⛪ Church finance digitization
🏥 Healthcare billing
🛒 Retail POS systems
🚚 Logistics and delivery

...you can now deploy your React Native app to Moniepoint POS terminals in minutes instead of weeks.

🎁 Open Source & Community

We've published react-native-moniepoint-pos-sdk to npm under a permissive license. Check it out:

📦 NPM Package: react-native-moniepoint-pos-sdk
💻 GitHub Repository: Kigbu/react-native-moniepoint-pos-sdk
⭐ Star it on GitHub if you find it useful!

Installation Guide

# 1. Install the package
npm install react-native-moniepoint-pos-sdk

# 2. Configure Moniepoint credentials (android/local.properties)
moniepointRepoUrl=https://open-repository.moniepoint.com/repository/public
moniepointUsername=your_username
moniepointPassword=your_password
moniepointSdkVersion=1.0.10

# 3. Initialize the SDK in MainApplication.kt
import com.moniepoint.paap.sdk.MoniepointPaapSdk
import com.moniepoint.paap.sdk.MoniepointPaapConfig
import com.moniepointpossdk.MoniepointPosPackage

val config = MoniepointPaapConfig.Builder()
    .enableCardPayment(true)
    .enablePrinting(true)
    .enableInAppPrinting(true)
    .build()

val moniepointSdk = MoniepointPaapSdk.initialize(this, config)

// Add to packages list
packages.add(MoniepointPosPackage(moniepointSdk))

# 4. Start building!

Full documentation and examples are included in the package README.

💭 Lessons Learned

1. React Native's Autolinking Had to Be Disabled

The Moniepoint SDK requires initialization with a configuration object. React Native's automatic package linking doesn't support constructor arguments, so we:

Disabled autolinking via react-native.config.js
Manually registered the package in MainApplication.kt with the initialized SDK instance

2. Credential Management is Critical

Developers need Moniepoint Maven credentials to download the SDK. We made this flexible:

Development: Use local.properties (gitignored)
CI/CD: Use environment variables
Team Sharing: Use gradle.properties.example as a template

3. Receipt Printing Requires Base64 Encoding

Moniepoint's printer accepts images as Base64 strings. We documented how to convert logos:

import {readFile} from 'react-native-fs';

const logoBase64 = await readFile('path/to/logo.png', 'base64');

4. TypeScript Definitions Matter

We provided full TypeScript definitions for better developer experience:

Autocomplete in VS Code
Type safety for receipt items
Clear error messages

🚀 What's Next?

We're working on:

✅ iOS Support — Currently Android-only, iOS support coming soon
✅ POS Transfer Support — Accept bank transfers at the terminal
✅ NFC Card Reading — Read ID cards and loyalty cards
✅ Example Apps — More real-world implementation examples
✅ Video Tutorials — Step-by-step integration guides

🤝 Join the Movement

If you're building fintech solutions in Nigeria or across Africa, we'd love to collaborate!

Try the SDK: npm install react-native-moniepoint-pos-sdk
Share Your Use Case: What are you building? Let us know in the comments!
Contribute: Found a bug or have a feature request? PRs welcome!
Learn More About Flopay: https://flopay.net/
Explore Moniepoint: https://moniepoint.com/

📌 Key Takeaways

Moniepoint POS SDK enables custom apps on POS terminals — a game-changer for Nigerian businesses
react-native-moniepoint-pos-sdk packages this power into an easy-to-use npm library
Flopay's success story (₦36B processed, 1.2M+ registrations) proves the business value
Open source wins — by sharing our work, we're accelerating fintech innovation in Africa

🔗 Useful Links

📦 NPM Package: react-native-moniepoint-pos-sdk
💻 GitHub Repository: Kigbu/react-native-moniepoint-pos-sdk
🐛 Report Issues: GitHub Issues
📖 Moniepoint Developer Docs: developer.moniepoint.com
🌐 Flopay Platform: https://flopay.net/
🇳🇬 Moniepoint: https://moniepoint.com/

🙏 Acknowledgments

I-Tech Platform Limited — For building Flopay and supporting this open-source initiative
Moniepoint — For providing an excellent PaaP SDK and comprehensive documentation
Our Field Agents — For the invaluable feedback that shaped this solution
The React Native Community — For the amazing tools and ecosystem

Have questions or want to share your implementation? Drop a comment below! 👇

Tags: #ReactNative #Android #Fintech #Nigeria #OpenSource #Moniepoint #Flopay #POS #MobilePayments #AfricanTech

About the Author:
I'm a software engineer at I-Tech Platform Limited, working on Flopay — Nigeria's leading revenue collection and remittance platform. We're transforming how governments, schools, churches, and enterprises manage their finances across Africa.

Connect with Flopay:

Website: https://flopay.net/
Trusted by: Adamawa State Govt, Yobe State Govt, COCIN, WAEC, Borno State IRS, Taraba State IRS, University of Maiduguri, and more.

Upgrading React Native from 0.74.3 to 0.79.5: A Journey Through Common Pitfalls and Solutions

Kigbu Amekalo — Tue, 29 Jul 2025 10:38:08 +0000

Introduction

Recently, I embarked on upgrading my React Native application from version 0.74.3 to 0.79.5. What I initially thought would be a straightforward process turned into an intensive debugging session that revealed several common pitfalls in React Native upgrades. This post documents the challenges we faced and the solutions that ultimately got our app running smoothly.

The Upgrade Process

Initial Setup

We started by updating the core dependencies in package.json:

{
  "dependencies": {
    "react": "19.0.0",
    "react-native": "0.79.5"
  },
  "devDependencies": {
    "@react-native-community/cli": "18.0.0",
    "@react-native/babel-preset": "0.79.5",
    "@react-native/eslint-config": "0.79.5",
    "@react-native/metro-config": "0.79.5",
    "@react-native/typescript-config": "0.79.5",
    "@types/react": "^19.0.0",
    "react-test-renderer": "19.0.0"
  }
}

Challenge #1: Kotlin Version Compatibility

Problem: Kotlin compilation errors in native modules like react-native-pager-view and react-native-screens.

Error:

Kotlin compilation failed: incompatible Kotlin versions

Solution: Updated kotlinVersion in android/build.gradle from 1.9.22 to 2.1.20:

buildscript {
    ext {
        kotlinVersion = "2.1.20"
    }
}

Challenge #2: Java Heap Space During Jetifier Transformation

Problem: Build process running out of memory during AndroidX migration.

Error:

Java heap space: GC overhead limit exceeded

Solution: Increased JVM heap size in android/gradle.properties:

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m

Challenge #3: Duplicate Classes from Android Support Library

Problem: Conflicts between old Android Support Library and AndroidX.

Error:

Duplicate class android.support.v4.app.INotificationSideChannel

Solution: Enabled Jetifier in android/gradle.properties:

android.enableJetifier=true

Challenge #4: Node Binary Path Issues

Problem: Gradle couldn't locate the Node.js executable.

Error:

A problem occurred starting process 'command 'node''

Solution: Explicitly set the Node binary path in android/gradle.properties:

NODE_BINARY=/Users/username/.nvm/versions/node/v22.15.1/bin/node

Challenge #5: Native Module Linking Errors

Problem: C++ linking errors with react-native-reanimated and missing codegen files.

Error:

undefined symbol: worklets::JSLogger::warnOnJS
CMake Error: add_subdirectory given source ... which is not an existing directory

Solution:

Updated react-native-reanimated to version 3.10.1
Ran codegen to generate missing native files:

   npx react-native codegen

Cleaned generated build directories to resolve duplicate CMake targets

Challenge #6: React Version Mismatch

Problem: The app was stuck on a black screen after splash screen due to React version incompatibility.

Error:

TypeError: undefined is not an object (evaluating 'ReactSharedInternals.S')
TypeError: Cannot read property 'default' of undefined

Solution: Ensured React and React Native versions were compatible:

React Native 0.79.5 requires React 19.x
Updated react to 19.0.0
Updated @types/react to ^19.0.0
Updated react-test-renderer to 19.0.0

Challenge #7: TypeScript Module Resolution

Problem: TypeScript couldn't resolve custom module paths.

Error:

Cannot find module 'core/constants/screen-names'

Solution: Updated tsconfig.json with proper path mappings:

{
  "extends": "@react-native/typescript-config",
  "compilerOptions": {
    "moduleResolution": "bundler",
    "baseUrl": "./src",
    "paths": {
      "core/*": ["core/*"],
      "setup/*": ["setup/*"],
      "utils/*": ["utils/*"],
      "components/*": ["components/*"]
    }
  }
}

Challenge #8: Metro Configuration Updates

Problem: Metro bundler needed updates for Node.js polyfills and module resolution.

Solution: Updated metro.config.js:

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');

const config = {
  resolver: {
    alias: {
      url: 'react-native-url-polyfill',
      crypto: 'react-native-crypto',
      stream: 'readable-stream',
      buffer: '@craftzdog/react-native-buffer',
    },
  },
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Key Configuration Updates

Android Configuration

android/app/build.gradle:

Updated React Native configuration block
Added autolinkLibrariesWithApp()
Updated JSC flavor
Simplified signing configurations

android/gradle.properties:

Enabled new architecture: newArchEnabled=true
Enabled Jetifier: android.enableJetifier=true
Increased heap size for memory-intensive builds

iOS Configuration

Gemfile:

Updated CocoaPods and ActiveSupport constraints
Added Ruby standard library gems for compatibility

ios/Podfile:

Simplified React Native pods resolution
Removed unnecessary imports

The Final Hurdle: App Stuck on Splash Screen

The most frustrating issue was the app getting stuck on a black screen after the splash screen. This was caused by:

Unreachable code in App.tsx: A return statement was preventing the main component from rendering
React version mismatch: The app was using React 18.2.0 instead of the required React 19.0.0
Module resolution issues: TypeScript couldn't resolve custom module paths

Lessons Learned

Always check React version compatibility: React Native 0.79.5 requires React 19.x
Clean builds are essential: Remove node_modules and rebuild when facing dependency issues
Memory allocation matters: Increase JVM heap size for complex Android builds
Native modules need attention: Update Kotlin versions and run codegen for native modules
TypeScript configuration is crucial: Ensure proper module resolution paths
Metro configuration updates: Add necessary polyfills and transformer options

Timeline

The entire upgrade process took approximately a full day of intensive debugging, including:

Initial dependency updates and configuration: 2 hours
Android build issues and Kotlin compatibility: 4 hours
iOS configuration and CocoaPods issues: 2 hours
React version mismatches and module resolution: 3 hours
Final testing and verification: 1 hour

The process involved significant back-and-forth debugging, with each fix often revealing new issues that needed to be addressed. This iterative approach, while time-consuming, was necessary to ensure all dependencies and configurations were properly aligned.

Conclusion

React Native upgrades can be challenging, but they're manageable with systematic debugging. The key is to:

Address one issue at a time
Keep detailed logs of errors
Understand the relationship between React and React Native versions
Don't hesitate to clean and rebuild when facing dependency issues
Be prepared for a full day of debugging when upgrading across multiple major versions

The upgrade to React Native 0.79.5 was successful, and the app now runs smoothly with improved performance and access to the latest features.

This post documents a real React Native upgrade experience. While the specific app details have been anonymized, the technical challenges and solutions are genuine and can help others facing similar issues during their own upgrades.

How to Deploy Multiple Versions of Your React Native App to TestFlight Using Xcode Cloud

Kigbu Amekalo — Sun, 13 Oct 2024 23:00:54 +0000

Managing multiple TestFlight apps, such as separate versions for production and development environments, can be quite challenging. However, by using Xcode Cloud’s Continuous Integration and Continuous Delivery (CICD) workflows with Bitbucket/Github, you can automate the deployment process.

This blog post will walk you through the process of deploying two different versions of the same React Native app to TestFlight: one for production (co.example.new) and one for development/debugging (co.example.new.debug). It covers creating separate build configurations, app bundle identifiers, app icons, and setting up workflows to automatically deploy the apps to TestFlight.

Step 1: Create App Bundle Identifiers

To handle two different versions of the app, you’ll need to create separate app bundle identifiers:

Go to the Apple Developer Portal.
Create two new App IDs:
- co.example.new for the production version.
- co.example.new.debug for the development/debugging version.

Step 2: Duplicate Build Configurations in Xcode

Now that the app IDs are ready, the next step is to create distinct build configurations for production and development in Xcode.

Open your project in Xcode.
Go to the Build Settings tab.
Find and duplicate the Release and Debug configurations. Name them Prod and Dev, respectively.
Update the PRODUCT_BUNDLE_IDENTIFIER field:
- Set Prod to use co.example.new.
- Set Dev to use co.example.new.debug.

Why Duplicate Build Configurations?

Duplicating the build configurations allows you to handle different environments (such as production and development) within the same project. Each configuration will use its respective bundle ID, app signing certificates, and provisioning profiles.

Step 3: Create a New Schema for the Development Build

After setting up the build configurations, you need to create a schema for the development build.

Under Product > Scheme > Manage Schemes, duplicate the default schema.
Rename the new schema to something like DevAppNameSchema.
Go to the Run and Archive actions of the new schema.
- In Run, set the build configuration to Dev.
- In Archive, also set the build configuration to Dev.

This new schema ensures that when you run or archive the app with the DevAppNameSchema, it uses the Dev build configuration, which is tied to the development bundle ID (co.example.new.debug).

Step 4: Configure Signing and Capabilities

Now, let's configure the app's signing and capabilities to use the correct provisioning profiles for each version.

In Xcode, under Targets > Signing & Capabilities, update the configurations:
- For the Prod build configuration, use the AppName provisioning profile.
- For the Dev build configuration, use the AppNameDebug provisioning profile.

This ensures that Xcode uses the appropriate provisioning profile when deploying each version of the app to TestFlight.

Step 5: Set Up Unique App Icons

To make it easy to differentiate between the production and development builds, you can configure unique app icons for each version of the app.

In the ios/Images.xcassets directory, duplicate the AppIcon.appiconset folder and rename it AppIcon-Debug.appiconset.
Place the development-specific app icon assets in the AppIcon-Debug.appiconset folder.
In Xcode:
- Under Build Settings, find the Primary App Icon Set Name field.
- Set the Prod build configuration to use AppIcon.
- Set the Dev build configuration to use AppIcon-Debug.

Now, when you run the production version of the app, it will show the standard icon, and the development version will display the debug-specific icon.

Step 6: Set Up Xcode Cloud CICD Workflows

Xcode Cloud helps automate your build and deployment process by triggering workflows when you push changes to your Bitbucket repository. For this setup, I created two workflows—one for each app version.

Workflow 1: Production Build Workflow

Go to Xcode Cloud in your Xcode project.
Set up a workflow for the main branch in your Bitbucket repository.
Under Environment Settings, configure the workflow to use the Prod build configuration.
Ensure that the workflow archives and uploads the app to TestFlight using the production provisioning profile and app bundle ID (co.example.new).

This workflow will be triggered whenever changes are pushed to the main branch, automatically deploying the production build to TestFlight.

Workflow 2: Development Build Workflow

Create a second workflow, this time connected to the dev branch in your Bitbucket repository.
Configure the workflow to use the Dev build configuration.
Ensure that the workflow archives and uploads the app to TestFlight using the development provisioning profile and app bundle ID (co.example.new.debug).

Now, any changes pushed to the dev branch will trigger the development workflow, deploying the development build to TestFlight.

Step 7: Testing the Workflows

To test the workflows, push some changes to the main branch and ensure that the production workflow is triggered in Xcode Cloud. Then, push changes to the dev branch to trigger the development workflow.

Each workflow should build, archive, and deploy the correct version of the app to TestFlight, using the appropriate app bundle ID and app icon.

Conclusion

By following these steps, you can efficiently manage multiple versions of your React Native app on TestFlight. Setting up separate build configurations, schemas, provisioning profiles, and app icons for production and development environments allows for a seamless CICD workflow using Xcode Cloud.

With automatic deployments triggered by Bitbucket pushes, your team can focus on development without worrying about manual TestFlight deployments. Whether you’re running beta tests or preparing for a production release, this setup keeps everything streamlined and organized.

Thank you for following along! I hope this guide simplifies your multi-environment deployment process. If you have any questions or suggestions, feel free to leave them in the comments below!

Happy coding and smooth deployments!

DEV Community: Kigbu Amekalo

Building a React Native NPM Library for Moniepoint POS SDK - Transforming Revenue Collection in Nigeria

Building a React Native NPM Library for Moniepoint POS SDK: A Journey from Field Agents to Open Source

🎯 The Problem We Solved

💡 Why Moniepoint POS?

🏗️ The Challenge: Making It Reusable

📦 Introducing react-native-moniepoint-pos-sdk

Installation

Quick Example

🚀 Real-World Use Cases in Nigeria

1. 🏛️ Government Revenue Collection (Our Use Case!)

2. 🏫 School Fees Collection

3. ⛪ Church Revenue Management

4. 🏥 Healthcare & Pharmacy Billing

5. 🛒 Retail POS with Inventory Sync

🔧 How We Built It

1️⃣ Native Android Module (Kotlin)

2️⃣ JavaScript Interface

3️⃣ Secure Credential Management

📊 Business Impact for Flopay

🇳🇬 Why This Matters for Nigerian Businesses

🎁 Open Source & Community

Installation Guide

💭 Lessons Learned

1. React Native's Autolinking Had to Be Disabled

2. Credential Management is Critical

3. Receipt Printing Requires Base64 Encoding

4. TypeScript Definitions Matter

🚀 What's Next?

🤝 Join the Movement

📌 Key Takeaways

🔗 Useful Links

🙏 Acknowledgments

Upgrading React Native from 0.74.3 to 0.79.5: A Journey Through Common Pitfalls and Solutions

Introduction

The Upgrade Process

Initial Setup

Challenge #1: Kotlin Version Compatibility

Challenge #2: Java Heap Space During Jetifier Transformation

Challenge #3: Duplicate Classes from Android Support Library

Challenge #4: Node Binary Path Issues

Challenge #5: Native Module Linking Errors

Challenge #6: React Version Mismatch

Challenge #7: TypeScript Module Resolution

Challenge #8: Metro Configuration Updates

Key Configuration Updates

Android Configuration

iOS Configuration

The Final Hurdle: App Stuck on Splash Screen

Lessons Learned

Timeline

Conclusion

How to Deploy Multiple Versions of Your React Native App to TestFlight Using Xcode Cloud

Step 1: Create App Bundle Identifiers

Step 2: Duplicate Build Configurations in Xcode

Why Duplicate Build Configurations?

Step 3: Create a New Schema for the Development Build

Step 4: Configure Signing and Capabilities

Step 5: Set Up Unique App Icons

Step 6: Set Up Xcode Cloud CICD Workflows

Workflow 1: Production Build Workflow

Workflow 2: Development Build Workflow

Step 7: Testing the Workflows

Conclusion

📦 Introducing `react-native-moniepoint-pos-sdk`