React Native CLI iOS Platform

React Native CLI iOS Platform provides iOS-specific command-line tools and utilities for React Native development. It enables developers to build, run, and manage React Native applications on iOS platforms, including support for simulators, devices, and comprehensive logging capabilities.

Package Information

• Package Name: @react-native-community/cli-platform-ios
• Package Type: npm
• Language: TypeScript
• Installation: npm install @react-native-community/cli-platform-ios

Core Imports

import { commands, findPodfilePaths, getArchitecture, installPods, dependencyConfig, projectConfig } from "@react-native-community/cli-platform-ios";

For CommonJS:

const { commands, findPodfilePaths, getArchitecture, installPods, dependencyConfig, projectConfig } = require("@react-native-community/cli-platform-ios");

Basic Usage

import { commands, installPods, getArchitecture } from "@react-native-community/cli-platform-ios";

// Access iOS CLI commands
const iosCommands = commands;
console.log(iosCommands.map(cmd => cmd.name)); // ['log-ios', 'run-ios', 'build-ios']

// Install CocoaPods dependencies
await installPods();

// Check if New Architecture is enabled
const isNewArchEnabled = await getArchitecture('./ios');
console.log('New Architecture enabled:', isNewArchEnabled);

Architecture

The package is built around several key components:

• CLI Commands: Pre-configured iOS-specific commands (build-ios, run-ios, log-ios) that integrate with React Native CLI
• Utility Functions: Shared functions for CocoaPods management and architecture detection
• Configuration Functions: iOS-specific project and dependency configuration wrappers
• Apple Platform Integration: Leverages @react-native-community/cli-platform-apple for shared functionality

Capabilities

CLI Commands

Array of iOS-specific CLI command objects for integration with React Native CLI. Each command provides iOS platform-specific functionality for development workflows.

interface Command {
  name: string;
  description: string;
  func: (...args: any[]) => Promise<void>;
  options: Option[];
  examples?: Example[];
}

interface Option {
  name: string;
  description: string;
  default?: any;
  parse?: (val: string) => any;
}

interface Example {
  desc: string;
  cmd: string;
}

const commands: Command[];

The commands array contains three iOS-specific commands:

build-ios Command:

• Name: "build-ios"
• Description: "builds your app for iOS platform"
• Options: Configuration options for iOS builds including mode, scheme, target, device selection
• Examples:
  • Build the app for all iOS devices in Release mode: npx react-native build-ios --mode "Release"

run-ios Command:

• Name: "run-ios"
• Description: "builds your app and starts it on iOS simulator"
• Options: Simulator selection, device targeting, build configuration, custom parameters
• Examples:
  • Run on a different simulator: npx react-native run-ios --simulator "iPhone SE (2nd generation)"
  • Run on a connected device: npx react-native run-ios --device "Max's iPhone"
  • Run on the AppleTV simulator: npx react-native run-ios --simulator "Apple TV" --scheme "helloworld-tvOS"

log-ios Command:

• Name: "log-ios"
• Description: "starts iOS device syslog tail"
• Options: Interactive device selection for log monitoring

CocoaPods Management

Podfile Discovery

Searches for all Podfile paths within a given directory, used for dependency management setup.

/**
 * Searches for all Podfile paths within a given directory
 * @param cwd - The current working directory to search from
 * @returns Array of relative paths to found Podfiles
 */
function findPodfilePaths(cwd: string): string[];

Usage Example:

import { findPodfilePaths } from "@react-native-community/cli-platform-ios";

const podfiles = findPodfilePaths(process.cwd());
console.log('Found Podfiles:', podfiles);
// Output: ['ios/Podfile', 'packages/mobile/ios/Podfile']

CocoaPods Installation

Installs CocoaPods dependencies for a React Native project with comprehensive error handling and configuration support.

interface PodInstallOptions {
  /** Skip running bundle install */
  skipBundleInstall?: boolean;
  /** Enable New Architecture */
  newArchEnabled?: boolean;
  /** Custom path to iOS folder (defaults to 'ios') */
  iosFolderPath?: string;
}

/**
 * Installs CocoaPods dependencies for a React Native project
 * @param loader - Progress spinner/loader for UI feedback (optional)
 * @param options - Configuration options for pod installation
 */
function installPods(loader?: Ora, options?: PodInstallOptions): Promise<void>;

Usage Examples:

import { installPods } from "@react-native-community/cli-platform-ios";
import ora from "ora";

// Basic installation
await installPods();

// With custom options
await installPods(undefined, {
  newArchEnabled: true,
  iosFolderPath: 'mobile/ios',
  skipBundleInstall: true
});

// With progress indicator
const spinner = ora('Installing CocoaPods...');
await installPods(spinner, { newArchEnabled: true });

Architecture Detection

Determines whether React Native's New Architecture is enabled by analyzing the Pods project configuration.

/**
 * Determines whether React Native's New Architecture is enabled
 * @param iosSourceDir - Path to the iOS source directory containing the Pods folder
 * @returns Promise resolving to true if New Architecture is enabled, false otherwise
 */
function getArchitecture(iosSourceDir: string): Promise<boolean>;

Usage Example:

import { getArchitecture } from "@react-native-community/cli-platform-ios";

const isNewArch = await getArchitecture('./ios');
if (isNewArch) {
  console.log('New Architecture is enabled');
} else {
  console.log('Using legacy architecture');
}

Configuration Functions

Dependency Configuration

iOS-specific dependency configuration function that wraps Apple platform functionality with iOS-specific parameters.

/**
 * iOS-specific dependency configuration function
 * Provides configuration for managing iOS dependencies in React Native projects
 */
const dependencyConfig: (root: string, userConfig: any) => any;

Project Configuration

iOS-specific project configuration function that wraps Apple platform functionality with iOS-specific parameters.

/**
 * iOS-specific project configuration function
 * Provides configuration for iOS project setup and management
 */
const projectConfig: (root: string, userConfig: any) => any;

Error Handling

Common Errors

CocoaPods Installation Errors:

• Missing iOS directory: Function returns early without error
• CocoaPods not installed: Automatic installation via gem with sudo fallback
• Pod install failures: Automatic repo update and retry

Architecture Detection Errors:

• Missing Pods.xcodeproj: Returns false (graceful fallback)
• File read errors: Returns false (graceful fallback)

Podfile Discovery Errors:

• Invalid directory: Returns empty array
• Permission errors: Skips inaccessible directories

Platform Requirements

• iOS Development: Requires Xcode and iOS development tools
• CocoaPods: Automatically installed if not present
• Node.js: Compatible with React Native CLI requirements
• Ruby/Bundler: Optional for Gemfile-based CocoaPods management

Integration Notes

This package is designed to be used as part of the React Native CLI ecosystem. The command objects are typically registered with the CLI rather than called directly. The utility functions can be used independently for custom tooling and scripts.