0
# React Native CLI iOS Platform
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @react-native-community/cli-platform-ios
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-native-community/cli-platform-ios`
10

11
## Core Imports
12

13
```typescript
14
import { commands, findPodfilePaths, getArchitecture, installPods, dependencyConfig, projectConfig } from "@react-native-community/cli-platform-ios";
15
```
16

17
For CommonJS:
18

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

23
## Basic Usage
24

25
```typescript
26
import { commands, installPods, getArchitecture } from "@react-native-community/cli-platform-ios";
27

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

32
// Install CocoaPods dependencies
33
await installPods();
34

35
// Check if New Architecture is enabled
36
const isNewArchEnabled = await getArchitecture('./ios');
37
console.log('New Architecture enabled:', isNewArchEnabled);
38
```
39

40
## Architecture
41

42
The package is built around several key components:
43

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

49
## Capabilities
50

51
### CLI Commands
52

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

55
```typescript { .api }
56
interface Command {
57
  name: string;
58
  description: string;
59
  func: (...args: any[]) => Promise<void>;
60
  options: Option[];
61
  examples?: Example[];
62
}
63

64
interface Option {
65
  name: string;
66
  description: string;
67
  default?: any;
68
  parse?: (val: string) => any;
69
}
70

71
interface Example {
72
  desc: string;
73
  cmd: string;
74
}
75

76
const commands: Command[];
77
```
78

79
The `commands` array contains three iOS-specific commands:
80

81
**build-ios Command:**
82
- **Name**: `"build-ios"`
83
- **Description**: `"builds your app for iOS platform"`
84
- **Options**: Configuration options for iOS builds including mode, scheme, target, device selection
85
- **Examples**:
86
  - Build the app for all iOS devices in Release mode: `npx react-native build-ios --mode "Release"`
87

88
**run-ios Command:**
89
- **Name**: `"run-ios"`
90
- **Description**: `"builds your app and starts it on iOS simulator"`
91
- **Options**: Simulator selection, device targeting, build configuration, custom parameters
92
- **Examples**:
93
  - Run on a different simulator: `npx react-native run-ios --simulator "iPhone SE (2nd generation)"`
94
  - Run on a connected device: `npx react-native run-ios --device "Max's iPhone"`
95
  - Run on the AppleTV simulator: `npx react-native run-ios --simulator "Apple TV" --scheme "helloworld-tvOS"`
96

97
**log-ios Command:**
98
- **Name**: `"log-ios"`
99
- **Description**: `"starts iOS device syslog tail"`
100
- **Options**: Interactive device selection for log monitoring
101

102
### CocoaPods Management
103

104
#### Podfile Discovery
105

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

108
```typescript { .api }
109
/**
110
 * Searches for all Podfile paths within a given directory
111
 * @param cwd - The current working directory to search from
112
 * @returns Array of relative paths to found Podfiles
113
 */
114
function findPodfilePaths(cwd: string): string[];
115
```
116

117
**Usage Example:**
118

119
```typescript
120
import { findPodfilePaths } from "@react-native-community/cli-platform-ios";
121

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

127
#### CocoaPods Installation
128

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

131
```typescript { .api }
132
interface PodInstallOptions {
133
  /** Skip running bundle install */
134
  skipBundleInstall?: boolean;
135
  /** Enable New Architecture */
136
  newArchEnabled?: boolean;
137
  /** Custom path to iOS folder (defaults to 'ios') */
138
  iosFolderPath?: string;
139
}
140

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

149
**Usage Examples:**
150

151
```typescript
152
import { installPods } from "@react-native-community/cli-platform-ios";
153
import ora from "ora";
154

155
// Basic installation
156
await installPods();
157

158
// With custom options
159
await installPods(undefined, {
160
  newArchEnabled: true,
161
  iosFolderPath: 'mobile/ios',
162
  skipBundleInstall: true
163
});
164

165
// With progress indicator
166
const spinner = ora('Installing CocoaPods...');
167
await installPods(spinner, { newArchEnabled: true });
168
```
169

170
### Architecture Detection
171

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

174
```typescript { .api }
175
/**
176
 * Determines whether React Native's New Architecture is enabled
177
 * @param iosSourceDir - Path to the iOS source directory containing the Pods folder
178
 * @returns Promise resolving to true if New Architecture is enabled, false otherwise
179
 */
180
function getArchitecture(iosSourceDir: string): Promise<boolean>;
181
```
182

183
**Usage Example:**
184

185
```typescript
186
import { getArchitecture } from "@react-native-community/cli-platform-ios";
187

188
const isNewArch = await getArchitecture('./ios');
189
if (isNewArch) {
190
  console.log('New Architecture is enabled');
191
} else {
192
  console.log('Using legacy architecture');
193
}
194
```
195

196
### Configuration Functions
197

198
#### Dependency Configuration
199

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

202
```typescript { .api }
203
/**
204
 * iOS-specific dependency configuration function
205
 * Provides configuration for managing iOS dependencies in React Native projects
206
 */
207
const dependencyConfig: (root: string, userConfig: any) => any;
208
```
209

210
#### Project Configuration
211

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

214
```typescript { .api }
215
/**
216
 * iOS-specific project configuration function
217
 * Provides configuration for iOS project setup and management
218
 */
219
const projectConfig: (root: string, userConfig: any) => any;
220
```
221

222
## Error Handling
223

224
### Common Errors
225

226
**CocoaPods Installation Errors:**
227
- Missing iOS directory: Function returns early without error
228
- CocoaPods not installed: Automatic installation via gem with sudo fallback
229
- Pod install failures: Automatic repo update and retry
230

231
**Architecture Detection Errors:**
232
- Missing Pods.xcodeproj: Returns `false` (graceful fallback)
233
- File read errors: Returns `false` (graceful fallback)
234

235
**Podfile Discovery Errors:**
236
- Invalid directory: Returns empty array
237
- Permission errors: Skips inaccessible directories
238

239
## Platform Requirements
240

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

246
## Integration Notes
247

248
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.