Skip to main content
Version: 1.0

Formulus Development

Complete guide for developing the Formulus mobile application.

Overview

This guide covers local development and production building for the Formulus React Native application.

Prerequisites

Required Tools

  • Node.js 18+ and npm
  • React Native CLI or Expo CLI
  • Java Development Kit (JDK) 11 or higher
  • Android Studio (for Android development)
  • Xcode (for iOS development, macOS only)
  • Android SDK (via Android Studio)
  • CocoaPods (for iOS, macOS only)

Platform-Specific Requirements

Android

  • Android SDK Platform 33+
  • Android SDK Build Tools
  • Android Emulator or physical device

iOS (macOS only)

  • Xcode 14+
  • CocoaPods
  • iOS Simulator or physical device

Local Development Setup

Step 1: Clone Repository

git clone https://github.com/OpenDataEnsemble/ode.git
cd ode/formulus

Step 2: Install Dependencies

npm install

Step 3: Install iOS Dependencies

cd ios
bundle install
bundle exec pod install
cd ..

Step 4: Generate API Client

Generate the Synkronus API client from OpenAPI spec:

npm run generate:api

Step 5: Generate WebView Injection Script

Generate the JavaScript injection script:

npm run generate

Step 6: Start Metro Bundler

npm start

Keep this terminal open. Metro is the JavaScript bundler.

Step 7: Run on Device/Emulator

npm run android

This will:

  1. Build the Android app
  2. Install it on your connected device/emulator
  3. Start the app
  4. Connect to Metro bundler

Development Workflow

Hot Reload

Changes to JavaScript/TypeScript files automatically reload:

  • Fast Refresh: React components update without losing state
  • Live Reload: Full app reload on some changes
  • Error Overlay: Errors displayed in app

Debugging

React Native Debugger

  1. Shake device or press Ctrl+M (Windows/Linux) or Cmd+M (macOS)
  2. Select "Debug"
  3. Chrome DevTools opens
  4. Set breakpoints and inspect code

Logging

import { console } from 'react-native'

console.log('Debug message')
console.warn('Warning message')
console.error('Error message')

View logs:

adb logcat | grep -i formulus

Testing

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

Building for Production

Android Production Build

Step 1: Generate Signing Key

keytool -genkeypair -v -storetype PKCS12 -keystore formulus-release.keystore -alias formulus -keyalg RSA -keysize 2048 -validity 10000

Step 2: Configure Signing

Edit android/gradle.properties:

FORMULUS_RELEASE_STORE_FILE=formulus-release.keystore
FORMULUS_RELEASE_KEY_ALIAS=formulus
FORMULUS_RELEASE_STORE_PASSWORD=your-store-password
FORMULUS_RELEASE_KEY_PASSWORD=your-key-password

Step 3: Build APK

cd android
./gradlew assembleRelease

APK location: android/app/build/outputs/apk/release/app-release.apk

Step 4: Build AAB (for Play Store)

cd android
./gradlew bundleRelease

AAB location: android/app/build/outputs/bundle/release/app-release.aab

iOS Production Build (macOS only)

Step 1: Configure Signing

  1. Open ios/Formulus.xcworkspace in Xcode
  2. Select project in navigator
  3. Go to "Signing & Capabilities"
  4. Select team and provisioning profile

Step 2: Build Archive

  1. In Xcode: Product → Archive
  2. Wait for build to complete
  3. Distribute App in Organizer

Step 3: Export IPA

  1. Select archive in Organizer
  2. Click "Distribute App"
  3. Choose distribution method (App Store, Ad Hoc, Enterprise)
  4. Follow export wizard

Project Structure

Key Directories

  • src/: TypeScript source code
  • android/: Android native code
  • ios/: iOS native code
  • assets/: Static assets (images, fonts, etc.)

Important Files

  • App.tsx: Main application component
  • package.json: Dependencies and scripts
  • tsconfig.json: TypeScript configuration
  • metro.config.js: Metro bundler configuration
  • babel.config.js: Babel configuration

Common Tasks

Adding Dependencies

npm install package-name

For native dependencies, may need to:

# Android
cd android && ./gradlew clean && cd ..

# iOS
cd ios && pod install && cd ..

Updating API Client

When Synkronus API changes:

npm run generate:api

Updating WebView Interface

When Formulus interface changes:

npm run generate

Cleaning Build

# Android
cd android && ./gradlew clean && cd ..

# iOS
cd ios && xcodebuild clean && cd ..

# Remove node_modules
rm -rf node_modules
npm install

Troubleshooting

Common Issues

Metro Bundler Won't Start:

  • Clear Metro cache: npm start -- --reset-cache
  • Delete node_modules and reinstall

Build Fails:

  • Clean build: cd android && ./gradlew clean
  • Check Java version: java -version (should be 11+)
  • Verify Android SDK is installed

iOS Build Fails:

  • Run pod install in ios/ directory
  • Clean build folder in Xcode
  • Check signing configuration

App Crashes on Launch:

  • Check logs: adb logcat or Xcode console
  • Verify API client is generated
  • Check WebView injection script is generated