Skip to main content

React Native Integration & Best Practices: Introduction

Introduction​

This guide provides best practices and strategies for integrating React Native into our existing shop platform. It is intended for developers who are building or extending native applications within the Archibald ecosystem.

The primary purpose of this guide is not to define every core API functionality of React Native, but rather to offer a how-to approach for best practices in using certain API functionalities, and to provide guidance on integrating concepts such as React Native usage on top of an existing shop platform.

Our platform supports multiple native runtimes, including React Native, Expo, and Capacitor, allowing for flexible development across various mobile environments, addressing different project needs and target audiences.

Prerequisites​

To ensure a smooth development experience with React Native, please ensure the following prerequisites are met:

Local Development Environment Setup​

Please ensure your local development environment is configured to support React Native development. This typically involves Node.js, Watchman, a Java Development Kit (JDK), and Android Studio or Xcode. Refer to the official React Native documentation for detailed setup instructions.

Bootstrap Verification Checklist​

  • Verify existing React Native bootstrap in project: Ensures the fundamental native project files (iOS/Android folders, package.json dependencies) are present and correctly initialized, preventing "module not found" errors at startup.
  • Inspect React Native entry files (e.g., App.tsx, index.native.ts): Confirms the application is correctly registered with AppRegistry. If the entry point is misconfigured, the native app will launch a blank screen or crash immediately.
  • Validate Metro configuration: Metro is the specific bundler for React Native. Incorrect configuration prevents the app from resolving packages, assets, or platform-specific file extensions (.native.js).
  • Validate Rspack configuration for React Native projects: Ensures the build system knows how to handle native syntax and excludes web-only modules, preventing build-time errors when sharing code between platforms.
  • Confirm platform-specific resolution (.native.tsx): Verifies that the bundler automatically picks up .native.tsx files instead of .tsx or .web.tsx. Without this, the app might try to render web components on mobile, causing crashes.
  • Audit app/ folder for React Native API usage: Helps identify existing patterns and dependencies to ensure consistency and avoid duplicating logic or introducing conflicting native libraries.
  • Identify browser API usage (window, document, localStorage): React Native runs in a JS environment without a DOM. Accessing global browser objects like window or document will cause immediate runtime crashes.
  • Identify SCSS imports inside shared components: React Native cannot parse CSS or SCSS. Importing these files in a native bundle will cause the build to fail; they must be conditionally excluded or replaced with CSS-in-JS.
  • Identify direct DOM manipulation: Methods like document.getElementById do not exist in React Native. These must be refactored to use React state or Refs to ensure the UI updates correctly on mobile.
  • Validate Node and CLI compatibility: React Native tooling (Metro, CocoaPods, Gradle) is highly sensitive to Node.js versions. Mismatches often lead to obscure build failures or debugger connection issues.