Skip to main content

Native Integration

Introduction​

Archibald simplifies the mobile development lifecycle by providing robust CLI capabilities to build and serve native applications. Instead of managing complex toolchains manually, developers can leverage Archibald's unified commands to compile bundles, launch simulators, and manage deployments.

The platform is designed to be flexible, supporting integration with various native runtimes:

  • React Native: For traditional native development with full control over native code.
  • Expo: For a managed workflow that accelerates development and simplifies deployment via EAS.
  • Capacitor: For projects that prefer to wrap the web application in a native shell.

Supported Runtimes & Scaffolding​

Description: Archibald allows you to easily add native capabilities to your existing project via the CLI. You can choose between Expo, Capacitor, or bare React Native depending on your project requirements.

  • How To: Use the add command to scaffold the necessary files and configuration for your chosen runtime. 
    # Add Expo (Recommended for most use cases)
    archibald add expo

    # Add Capacitor (For wrapping existing web apps)
    archibald add capacitor
  • Best Practices: Use Expo for new native projects to leverage EAS (Expo Application Services) for building and updating apps OTA. Use Capacitor if you have a mature PWA that you want to deploy to app stores with minimal changes.

CLI & Development Workflow​

Description: The Archibald CLI wraps standard native tooling (Metro, Xcode, Android Studio) to provide a unified development experience. It handles configuration injection, environment variables, and port management automatically.

  • How To: Start the development server (Metro Bundler) and launch simulators. 
    # Start the Metro Bundler and launch the simulator (iOS or Android)
    archibald serve -p app -n ios

    # Build the native bundle or binary
    archibald build -p app -n ios -m production
  • Best Practices: Always use archibald serve -p app -n <ios|android> instead of running npx expo start directly. This ensures that the Archibald configuration (tenants, environments, secrets) is correctly injected into the native runtime environment.

Platform Separation Strategy​

Description: Sharing code between Web and Native is a core feature of Archibald. To handle platform-specific logic (like DOM access vs Native APIs), we use file-based separation.

  • How To: Create platform-specific files using the .native.tsx extension. The bundler will automatically resolve the correct file based on the target platform. 
    // Button.tsx (Web implementation)
    export const Button = () => <button>Click me</button>;

    // Button.native.tsx (Native implementation)
    import { TouchableOpacity, Text } from 'react-native';
    export const Button = () => (
        <TouchableOpacity><Text>Click me</Text></TouchableOpacity>
    );
  • Best Practices: Adhere to the "No DOM in Native" rule. Never access window, document, or localStorage in shared code unless it is guarded or abstracted behind a platform-specific interface.