0
# Command System
1

2
Complete type definitions for React Native CLI command development with support for standard commands, detached commands, and command options with conditional typing.
3

4
## Capabilities
5

6
### Command Functions
7

8
Type-safe command function signatures for both standard and detached command modes.
9

10
```typescript { .api }
11
/**
12
 * Standard command function signature
13
 * @param argv - Command line arguments array
14
 * @param ctx - Complete CLI configuration context
15
 * @param args - Parsed command arguments
16
 */
17
type CommandFunction<Args = Object> = (
18
  argv: Array<string>,
19
  ctx: Config,
20
  args: Args,
21
) => Promise<void> | void;
22

23
/**
24
 * Detached command function signature with different parameter order
25
 * @param argv - Command line arguments array
26
 * @param args - Parsed command arguments
27
 * @param ctx - Complete CLI configuration context
28
 */
29
type DetachedCommandFunction<Args = Object> = (
30
  argv: string[],
31
  args: Args,
32
  ctx: Config,
33
) => Promise<void> | void;
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { CommandFunction, DetachedCommandFunction, Config } from "@react-native-community/cli-types";
40

41
// Standard command
42
const buildCommand: CommandFunction = async (argv, ctx, args) => {
43
  console.log(`Building project at ${ctx.root}`);
44
  console.log(`React Native version: ${ctx.reactNativeVersion}`);
45
  
46
  if (ctx.project.android) {
47
    console.log(`Android app: ${ctx.project.android.appName}`);
48
  }
49
};
50

51
// Detached command (different parameter order)
52
const detachedCommand: DetachedCommandFunction = async (argv, args, ctx) => {
53
  console.log(`Detached command with args:`, args);
54
  console.log(`Project root: ${ctx.root}`);
55
};
56
```
57

58
### Command Options
59

60
Configuration options for command-line arguments with parsing and default value support.
61

62
```typescript { .api }
63
/**
64
 * Command option configuration
65
 * @template T - Type of default value function
66
 */
67
type CommandOption<T = (ctx: Config) => OptionValue> = {
68
  /** Option name (e.g., "--verbose" or "-v") */
69
  name: string;
70
  /** Human-readable description for help text */
71
  description?: string;
72
  /** Function to parse string value into desired type */
73
  parse?: (val: string) => any;
74
  /** Default value or function that returns default value */
75
  default?: OptionValue | T;
76
};
77

78
type OptionValue = string | boolean | number;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { CommandOption, Config } from "@react-native-community/cli-types";
85

86
// Static default value
87
const verboseOption: CommandOption = {
88
  name: "--verbose",
89
  description: "Enable verbose logging",
90
  default: false
91
};
92

93
// Dynamic default based on config
94
const platformOption: CommandOption<(ctx: Config) => string> = {
95
  name: "--platform",
96
  description: "Target platform",
97
  parse: (val: string) => val.toLowerCase(),
98
  default: (ctx: Config) => ctx.project.android ? "android" : "ios"
99
};
100

101
// Custom parser
102
const countOption: CommandOption = {
103
  name: "--count",
104
  description: "Number of iterations",
105
  parse: (val: string) => parseInt(val, 10),
106
  default: 1
107
};
108
```
109

110
### Command Definitions
111

112
Complete command definitions with conditional typing for detached mode and comprehensive metadata support.
113

114
```typescript { .api }
115
/**
116
 * Complete command definition with conditional typing
117
 * @template IsDetached - Whether this is a detached command
118
 */
119
type Command<IsDetached extends boolean = false> = {
120
  /** Command name as used in CLI */
121
  name: string;
122
  /** Human-readable description */
123
  description?: string;
124
  /** Whether this is a detached command */
125
  detached?: IsDetached;
126
  /** Usage examples for help text */
127
  examples?: Array<{
128
    desc: string;
129
    cmd: string;
130
  }>;
131
  /** Package information */
132
  pkg?: {
133
    name: string;
134
    version: string;
135
  };
136
  /** Command implementation function */
137
  func: IsDetached extends true
138
    ? DetachedCommandFunction<Object>
139
    : CommandFunction<Object>;
140
  /** Command-line options */
141
  options?: Array<
142
    CommandOption<
143
      IsDetached extends true ? () => OptionValue : (ctx: Config) => OptionValue
144
    >
145
  >;
146
};
147

148
/**
149
 * Type alias for detached commands
150
 */
151
type DetachedCommand = Command<true>;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { Command, CommandFunction, DetachedCommand, DetachedCommandFunction } from "@react-native-community/cli-types";
158

159
// Standard command
160
const startCommand: Command = {
161
  name: "start",
162
  description: "Start the React Native development server",
163
  examples: [
164
    {
165
      desc: "Start with default configuration",
166
      cmd: "npx react-native start"
167
    },
168
    {
169
      desc: "Start on specific port",
170
      cmd: "npx react-native start --port 8082"
171
    }
172
  ],
173
  func: async (argv, ctx, args) => {
174
    console.log("Starting development server...");
175
  },
176
  options: [
177
    {
178
      name: "--port",
179
      description: "Port to run server on",
180
      parse: (val: string) => parseInt(val, 10),
181
      default: 8081
182
    },
183
    {
184
      name: "--reset-cache",
185
      description: "Reset bundler cache",
186
      default: false
187
    }
188
  ]
189
};
190

191
// Detached command
192
const detachedBuildCommand: DetachedCommand = {
193
  name: "build",
194
  description: "Build the application",
195
  detached: true,
196
  pkg: {
197
    name: "@react-native-community/cli-build",
198
    version: "1.0.0"
199
  },
200
  func: async (argv, args, ctx) => {
201
    console.log("Building application...");
202
  },
203
  options: [
204
    {
205
      name: "--release",
206
      description: "Build for release",
207
      default: () => false  // Note: detached commands use () => OptionValue
208
    }
209
  ]
210
};
211
```
212

213
### Command Integration
214

215
How commands integrate with the broader CLI configuration system.
216

217
```typescript { .api }
218
// Commands are part of the main Config interface
219
interface Config {
220
  // ... other properties
221
  commands: Command[];
222
  // ... other properties
223
}
224

225
// User dependency configurations can also provide commands
226
type UserDependencyConfig = {
227
  // ... other properties
228
  commands: Command[];
229
  // ... other properties
230
};
231
```
232

233
**Usage Examples:**
234

235
```typescript
236
import { Config, Command } from "@react-native-community/cli-types";
237

238
// Adding commands to configuration
239
function addCustomCommand(config: Config, newCommand: Command): Config {
240
  return {
241
    ...config,
242
    commands: [...config.commands, newCommand]
243
  };
244
}
245

246
// Finding commands by name
247
function findCommand(config: Config, name: string): Command | undefined {
248
  return config.commands.find(cmd => cmd.name === name);
249
}
250

251
// Filtering detached commands
252
function getDetachedCommands(config: Config): DetachedCommand[] {
253
  return config.commands.filter(cmd => cmd.detached === true) as DetachedCommand[];
254
}
255
```