Skip to main content

React Native Integration & Best Practices: Bootstrap Project

React Native Bootstrap in Existing Project​

This section provides a high-level guide to bootstrapping a new React Native application within an existing project that already has a shop platform and a shared package.

Fresh Environment Setup (iOS & Android)​

Before bootstrapping a new application, ensure your local development environment is configured correctly for both iOS and Android. This is especially important for a fresh setup.

iOS Bootstrap​

To build and run the application on iOS, you need to set up the Apple development environment:

  1. Install Xcode: Download and install Xcode from the Mac App Store. Ensure you also install the Command Line Tools (usually prompted upon first opening Xcode, or by running xcode-select --install in your terminal).
  2. Install CocoaPods: CocoaPods is the dependency manager for Swift and Objective-C Cocoa projects. It is required for linking React Native native modules. These are typically installed automatically when the app build is started; manual installation is only necessary if you encounter issues. 
    sudo gem install cocoapods
    (Alternatively, you can install it via Homebrew: brew install cocoapods)

Android Setup Bootstrap​

To build and run the application on Android, you need to set up the Android development environment:

  1. Install Android Studio: Download and install Android Studio from the official developer website. Make sure to install the Android SDK, Android SDK Platform, and Android Virtual Device during the setup process.
  2. Gradle and Expo 56 Compatibility: Ensure your Gradle setup matches the requirements for Expo SDK 56. Verify these configurations in your Android project files:
    • Build Tools:
      • Gradle Version: 8.14.3
      • Android Gradle Plugin (AGP): (Inspect the project's build files to determine the exact version)
      • Java (JVM) Target: 17 (both for Java and Kotlin)
      • Kotlin Version: 2.1.20
    • Android Configuration:
      • Compile SDK: 36
      • Target SDK: 36
      • Min SDK: 24
      • Build Tools: 36.0.0

React Native & Expo Packages​

Ensure the following core packages are part of your setup. The versions below are the ones pinned in the workspace catalog (pnpm-workspace.yaml), which is the source of truth — check it rather than this list when in doubt:

  • react-native: 0.85.3
  • expo: ~56.0.16
  • expo-router: ~56.2.15
  • react-native-nitro-modules: 0.36.1
  • react-native-unistyles: ~3.3.0
  • expo-dev-client: ~56.0.23
  • expo-updates: ~56.0.22

archibald add expo installs this set for you.

Project Structure Overview​

The expected project structure is as follows:

  • packages/: This directory contains shared packages, business logic, hooks, and platform-agnostic utilities used across different applications and platforms. It serves as the boundary for code reuse.
  • src/shop/: This directory contains the web-based shop implementation, including DOM-specific components and routing.
  • src/app/: This is where the new native application (React Native/Expo) will be located. It contains native-specific components, navigation, and configuration.

src/app/ only needs the files it actually overrides — anything absent there resolves to its src/shop/ counterpart through shadowing.

Bootstrap Steps​

  1. Install required dependencies: Ensure that all the required react-native dependencies are installed in the package.json of the basic template.
  2. Create native entry file: Create a native entry file (e.g., templates/basic/index.js). This file will be the main entry point for your native application.
  3. Create root App.tsx: Create a root App.tsx component in your templates/basic/src/app/client directory. This component will be the root of your React Native application.
  4. Configure Rspack resolution rules: When sharing code between web and native platforms, your web bundler (Rspack) must be configured to prioritize web-specific files. This is already configured in the @archibald/build package.
  5. Configure Metro bundler: Configure the Metro bundler to work with your project structure and dependencies. The @archibald/native package provides a preset to simplify this configuration.
  6. Validate native build on simulator:
    • iOS: Run archibald serve -p app -n ios. Ensure the simulator launches, the app installs, and Metro connects.
    • Android: Run archibald serve -p app -n android. Ensure the emulator launches (or device connects) and the app builds successfully.
    • Troubleshooting: If the build fails, check for linking errors (CocoaPods) or missing environment variables.
  7. Validate no DOM usage in native bundle: Ensure that your native bundle does not contain any code that accesses the DOM.

Migration Issues & Solutions​

When integrating React Native into an existing project, you may encounter some challenges, especially when dealing with shared components that were originally designed for the web.

SCSS in Shared Components​

  • Issue: SCSS styles used in shared components will not compile in a React Native environment. React Native uses a flexbox layout engine (Yoga) that does not support CSS cascading, pseudo-classes, or media queries in the same way browsers do.
  • Best Practice: The recommended approach is to recreate the component using React Native's styling system (e.g., StyleSheet or a styling library like react-native-unistyles). Avoid trying to reuse SCSS styles or using transpilers, as the fundamental rendering differences often lead to poor performance and visual inconsistencies.

Shared HTML Atoms​

  • Issue: Shared components that use base HTML tags (e.g., <div>, <span>, <img>) are not compatible with React Native.
  • Best Practice: The best practice is to create native equivalents of these components using React Native's primitives (e.g., <View>, <Text>, <Image>). A gradual migration approach is recommended, where you start by rebuilding the most basic components and then move on to more complex ones. Avoid mixing HTML and React Native components, as this can lead to unpredictable behavior and a poor user experience.

Gradual Migration Strategy​

We recommend a phased migration approach when moving a web-based application to React Native:

  1. Rebuild primitives first: Start by rebuilding the most basic components (e.g., buttons, inputs, etc.).
  2. Rebuild atoms next: Once you have a solid set of primitives, you can start rebuilding the atoms (e.g., product cards, etc.).
  3. Rebuild molecules: After the atoms, you can move on to the molecules (e.g., product carousels, etc.).
  4. Rebuild feature modules: Finally, you can rebuild the feature modules (e.g., the checkout process, etc.).

This phased approach allows you to gradually migrate your application to React Native without having to do a full rewrite.