React Native Integration & Best Practices: Development Workflow

Development Workflow and Configuration

This section outlines the fundamental principles and strategies for developing robust and maintainable React Native applications within our ecosystem.

CLI Command Reference

The Archibald Native CLI (@archibald/native) wraps standard Expo and EAS tooling to provide a unified interface for development, building, and deployment. Below is a reference of the available commands and flags.

Development (npm run serve:app)

Used for local development. Starts the Metro bundler or runs the native app locally.

Command	Description
npm run serve:app -- --native	Default. Starts Expo and the Metro bundler in interactive mode. Use i (iOS) or a (Android) to launch simulators.
npm run serve:app -- --native=ios	Starts and builds iOS as a development version locally, and installs it on the simulator/device.
npm run serve:app -- --native=android	Starts the Android app locally. Note: In order for Android to work, you must first have a build ready with a debug.apk. See the Build section below for instructions.
npm run serve:app -- --native --clear	Clears the Metro bundler cache before starting. Useful for resolving stale dependency issues.

Build & Deployment (npm run build:app)

Used for building binaries, generating configuration, and deploying updates.

Android Local Debug Build Prerequisite: Run the following command to create a build for Android:

npm run build:app -- --native=android

Command	Description
npm run build:app -- --eas --platform=ios	Triggers a cloud build via EAS Build. Uses the profile defined in eas.json (default: production).
npm run build:app -- --prebuild	Runs Expo Prebuild. Generates the ios/ and android/ native directories based on your config.
npm run build:app -- --update	Publishes an OTA Update via EAS Update. Updates the JS bundle for existing users without a store release.
npm run build:app -- --upload	Submits a binary to the App Store or Google Play Store via EAS Submit.

Common Flags

These flags can be combined with the commands above.

Flag	Description
--profile=<name>	Specifies the build profile (e.g., development, preview, production). Default: production.
--platform=<os>	Specifies the target platform (ios, android, all).
--mode=<mode>	Sets the environment mode (e.g., development, production). Affects environment variable injection.
--local	When used with --eas, runs the EAS build locally on your machine instead of the cloud.

Expo Application Services

We use EAS (Expo Application Services) for building and submitting our native applications. EAS Build is a hosted service that compiles your project in the cloud, handling the complexity of native build environments.

Core Concepts

• eas.json: The configuration file that defines build profiles (e.g., development, preview, production). It controls build credentials, environment variables, and distribution methods.
• Build Profiles:
  • Development: Creates a custom development client (like Expo Go, but with your native code).
  • Preview: Builds the app for internal distribution (e.g., TestFlight, Internal Testing).
  • Production: Builds the optimized binary for App Store submission.

Creating & Publishing a Production Build

To create a production build and publish it to the App Store or Google Play, follow these steps:

1. Login to EAS: Ensure you are logged in to your Expo account via the CLI: eas login
2. Configure Production Profile: Verify your eas.json has a production profile configured.
3. Trigger the Build: Run the build command for the desired platform.

   eas build --profile production --platform ios

4. Submit to Stores: Once the build is successful, you can submit it directly to the app stores using EAS Submit.

   eas submit --platform ios

Metro Configuration Strategy

Configuring Metro correctly is critical for React Native in a monorepo environment like Archibald. The default Metro configuration often struggles with symlinks and hoisted dependencies (packages located in the root node_modules).

To simplify this, we provide a preset configuration in @archibald/native (a custom internal package providing a pre-configured set of Metro bundler rules developed internally for Archibald monorepos). This preset handles:

• Monorepo Resolution: Correctly resolving dependencies from the root node_modules.
• Symlink Support: Enabling Metro to follow symlinks (essential for local package development).
• Asset Extensions: Configuring asset resolution for images and fonts.
• Source Extensions: Prioritizing .native.ts and .native.tsx extensions.

Best Practice Configuration:

Your metro.config.js should extend the Expo default config with our preset:

const { getDefaultConfig } = require('expo/metro-config');
const { preset } = require('@archibald/native');

const config = getDefaultConfig(__dirname);

module.exports = {
  ...config,
  ...preset,
};