CLI Interface

Command line tool for quickly starting an inspector proxy server with configurable options. The CLI provides a simple way to launch a complete debugging infrastructure for React Native development.

Capabilities

Command Line Options

The CLI accepts the following options for configuring the inspector proxy server:

interface CLIOptions {
  port: number;    // Port to run inspector proxy on
  root: string;    // Root folder of metro project
}

CLI Usage

# Install globally to use as command
npm install -g metro-inspector-proxy

# Start with default settings (port 8081, current directory as root)
metro-inspector-proxy

# Specify custom port
metro-inspector-proxy --port 9090
metro-inspector-proxy -p 9090

# Specify project root directory
metro-inspector-proxy --root /path/to/my/react/native/project
metro-inspector-proxy -r /path/to/my/react/native/project

# Combined options
metro-inspector-proxy --port 9090 --root /path/to/project

Option Details

--port, -p (number)

• Description: Port to run inspector proxy on
• Default: 8081
• Usage: Specifies which port the HTTP server will listen on for both HTTP endpoints and WebSocket connections

--root, -r (string)

• Description: Root folder of metro project
• Default: Empty string (current directory)
• Usage: Sets the project root directory used for resolving relative source file paths during debugging

CLI Implementation

The CLI is implemented using the yargs library for argument parsing:

const yargs = require('yargs');
const { runInspectorProxy } = require('./index');

const argv = yargs
  .option('port', {
    alias: 'p',
    describe: 'port to run inspector proxy on',
    type: 'number',
    default: 8081,
  })
  .option('root', {
    alias: 'r', 
    describe: 'root folder of metro project',
    type: 'string',
    default: '',
  })
  .parseSync();

runInspectorProxy(argv.port, argv.root);

Server Startup

When started via CLI, the inspector proxy server automatically:

1. Creates HTTP server on the specified port binding to 127.0.0.1
2. Sets up HTTP endpoints:
   • GET /json - List of inspectable pages
   • GET /json/list - Alternative pages endpoint
   • GET /json/version - Chrome DevTools protocol version
3. Creates WebSocket endpoints:
   • /inspector/device - For React Native devices to connect
   • /inspector/debug - For Chrome DevTools to connect
4. Enables device discovery with automatic page polling
5. Handles debugger sessions with message forwarding and protocol translation

Integration with Development Workflow

The CLI tool integrates seamlessly with React Native development:

# Terminal 1: Start Metro bundler
npx react-native start

# Terminal 2: Start inspector proxy (if not using Metro's built-in proxy)
metro-inspector-proxy --port 8081 --root /path/to/MyReactNativeApp

# Terminal 3: Start React Native app
npx react-native run-ios
# or
npx react-native run-android

Once running, developers can:

1. Open Chrome and navigate to chrome://inspect
2. Click "Configure..." and add localhost:8081 to the target discovery settings
3. The React Native app should appear in the "Remote Target" list
4. Click "inspect" to open Chrome DevTools for debugging

Process Management

The CLI tool runs as a persistent process that:

• Listens for device connections from React Native apps
• Manages multiple simultaneous debugger sessions
• Handles app reloads and reconnections gracefully
• Provides console output for connection events and errors

To stop the server, use Ctrl+C (SIGINT) in the terminal where it's running.

Error Handling

The CLI provides basic error handling:

• Invalid port numbers are handled by yargs validation
• Network binding errors are logged to console
• WebSocket connection errors are managed per-connection
• File system errors for source resolution are reported to debugger console

Environment Considerations

The inspector proxy CLI is designed for development environments and:

• Only binds to localhost (127.0.0.1) for security
• Should not be used in production environments
• Requires Node.js version 18 or higher
• Works with both iOS Simulator/device and Android emulator/device