or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bundling.mdcli-commands.mdconfiguration.mddevelopment-server.mdindex.md
tile.json

cli-commands.mddocs/

CLI Commands

Command-line interface providing build, serve, and dependency analysis commands essential for integration with build tools, deployment pipelines, and development workflows. Metro's CLI enables both development and production bundling from the command line.

Capabilities

Build Command

Generates a production JavaScript bundle from an entry point with comprehensive build options.

metro build <entry>

# Required Arguments:
#   <entry>              Entry point file path

# Build Options:
#   --out, -O <string>           Output file path (required)
#   --platform, -p <string>      Target platform (ios, android, web)
#   --dev, -g                    Enable development mode
#   --minify, -z                 Enable minification
#   --source-map                 Generate source maps
#   --source-map-url <string>    Custom source map URL

# Performance Options:
#   --max-workers, -j <number>   Maximum number of worker threads

# Configuration Options:
#   --project-roots, -P <string[]>    Project root directories
#   --config, -c <string>             Configuration file path
#   --transform-option <string[]>     Custom transform options (key=value)
#   --resolver-option <string[]>      Custom resolver options (key=value)

# Cache Options:
#   --reset-cache                Reset transform cache (deprecated)

# Deprecated Options:
#   --output-type, -t <string>   Output type (deprecated)
#   --legacy-bundler             Use legacy bundler (deprecated)

Usage Examples:

# Basic production build
metro build src/index.js --out dist/bundle.js --minify

# Platform-specific build with source maps
metro build src/index.js --out dist/app.ios.js --platform ios --source-map

# Development build with custom config
metro build src/index.js --out dist/debug.js --dev --config metro.dev.config.js

# Build with custom transform options
metro build src/index.js --out dist/bundle.js \
  --transform-option enableFlow=true \
  --transform-option stripTypes=true

# Multi-platform build script
metro build src/index.js --out dist/bundle.web.js --platform web --minify
metro build src/index.js --out dist/bundle.ios.js --platform ios --minify
metro build src/index.js --out dist/bundle.android.js --platform android --minify

Serve Command

Starts a development server for on-demand bundling with hot module reloading support.

metro serve
# or
metro start

# Server Options:
#   --host, -h <string>          Host to bind server (default: localhost)
#   --port, -p <number>          Port to bind server (default: 8081)

# HTTPS Options:
#   --secure-server-options, -s <string>  HTTPS server options (dot notation)

# Performance Options:
#   --max-workers, -j <number>   Maximum number of worker threads

# Development Options:
#   --hmr-enabled, --hmr         Enable Hot Module Reloading

# Configuration Options:
#   --project-roots, -P <string[]>    Project root directories
#   --config, -c <string>             Configuration file path

# Cache Options:
#   --reset-cache                Reset transform cache (deprecated)

# Deprecated HTTPS Options:
#   --secure                     Enable HTTPS (deprecated)
#   --secure-key <string>        HTTPS private key path (deprecated)
#   --secure-cert <string>       HTTPS certificate path (deprecated)

Usage Examples:

# Basic development server
metro serve

# Custom host and port
metro serve --host 0.0.0.0 --port 3000

# HTTPS server with custom certificates
metro serve --secure-server-options.key=./certs/key.pem --secure-server-options.cert=./certs/cert.pem

# Development server with custom config
metro serve --config metro.dev.config.js --hmr

# Production-like server without HMR
metro serve --port 8080 --max-workers 4

Dependencies Command

Analyzes and lists all dependencies for a given entry point, useful for understanding bundle composition and debugging dependency issues.

metro get-dependencies [entryFile]

# Entry Options:
#   --entry-file <string>        Absolute path to entry JS file (required)

# Output Options:
#   --output <string>            File to save dependency list

# Build Options:
#   --platform <string>          Target platform for dependency resolution
#   --dev                        Include development dependencies (default: true)

# Analysis Options:
#   --transformer <string>       Custom transformer to use
#   --max-workers <number>       Maximum number of worker threads
#   --verbose                    Enable verbose logging (default: false)

Usage Examples:

# Analyze dependencies for entry file
metro get-dependencies --entry-file ./src/index.js

# Platform-specific dependency analysis
metro get-dependencies --entry-file ./src/index.js --platform ios

# Save dependencies to file
metro get-dependencies --entry-file ./src/index.js --output ./deps.json

# Verbose dependency analysis
metro get-dependencies --entry-file ./src/index.js --verbose

# Production dependencies only
metro get-dependencies --entry-file ./src/index.js --dev=false

CLI Integration

Metro provides programmatic CLI integration for custom build tools and scripts.

/**
 * Attach Metro CLI commands to a yargs instance
 * @param yargs - Yargs instance to attach commands to
 * @param options - Options to enable/disable specific commands
 * @returns Enhanced yargs instance with Metro commands
 */
function attachMetroCli(
  yargs: Yargs.Argv,
  options?: AttachMetroCLIOptions
): Yargs.Argv;

interface AttachMetroCLIOptions {
  /** Enable build command (default: enabled) */
  build?: BuildCommandOptions | null;
  /** Enable serve command (default: enabled) */  
  serve?: ServeCommandOptions | null;
  /** Enable dependencies command (default: enabled) */
  dependencies?: unknown;
}

type BuildCommandOptions = Record<string, unknown> | null;
type ServeCommandOptions = Record<string, unknown> | null;

Usage Example:

import yargs from "yargs";
import { attachMetroCli } from "metro";

// Create custom CLI with Metro commands
const cli = attachMetroCli(yargs, {
  build: {}, // Enable build command
  serve: {}, // Enable serve command  
  dependencies: {}, // Enable dependencies command
});

// Add custom commands
cli.command(
  "analyze",
  "Analyze bundle size",
  () => {},
  async (argv) => {
    // Custom analysis logic
  }
);

// Parse command line arguments
cli.demandCommand(1).argv;

Command Output and Exit Codes

Build Command Output

# Successful build
✓ Built bundle in 1.2s
Bundle size: 245KB (78KB gzipped)
Source map: bundle.js.map

# Build with progress
Building bundle... ████████████████████ 100% (124/124 files)
✓ Built bundle in 2.1s

# Build error
✗ Failed to build bundle
Error: Cannot resolve module 'missing-module'
  at src/index.js:1:15
Exit code: 1

Serve Command Output

# Server startup
Metro server listening on http://localhost:8081
⚡ Fast bundling enabled
🔥 Hot reloading enabled

# Bundle requests
GET /index.bundle?platform=web -> 200 (1.2s)
GET /assets/logo.png -> 200 (45ms)

# Server shutdown
Metro server shutting down...
✓ Server closed gracefully

Dependencies Command Output

# JSON output format (default)
[
  "./src/index.js",
  "./src/components/App.js",
  "./node_modules/react/index.js",
  "./node_modules/react-native/index.js"
]

# Verbose output
Analyzing dependencies for: ./src/index.js
Platform: web
Found 47 dependencies:
  - ./src/index.js (entry)
  - ./src/components/App.js
  - ./node_modules/react/index.js
  - ...

Exit Codes

# Success
0    # Command completed successfully

# Errors  
1    # General error (build failed, server startup failed, etc.)
2    # Invalid command line arguments
3    # Configuration error
4    # File system error (missing files, permission denied)

Environment Variables

Metro CLI respects several environment variables for configuration:

# Development settings
NODE_ENV=development    # Enable development mode
NODE_ENV=production     # Enable production optimizations

# Performance settings  
METRO_MAX_WORKERS=4     # Override max workers
METRO_CACHE_DIR=/tmp    # Custom cache directory

# Debugging
DEBUG=metro:*           # Enable debug logging
METRO_VERBOSE=1         # Enable verbose output