Development Server Management

The Medusa CLI provides comprehensive development server management capabilities for running Medusa Commerce applications in development, production, and cluster modes. These commands are only available within Medusa project directories.

Capabilities

Development Server

Starts the Medusa development server with file watching and automatic reloading for development workflows.

medusa develop

Options:

• -H, --host <string>: Set server host (default: localhost)
• -p, --port <string>: Set server port (default: 9000 or PORT environment variable)

Usage Examples:

# Start development server with defaults
medusa develop

# Start on custom host and port
medusa develop --host 0.0.0.0 --port 3000

# Start with port from environment or custom
medusa develop -p 8080

Behavior:

• Enables file watching for automatic server restarts on code changes
• Sets NODE_ENV to 'development' if not already set
• Runs indefinitely until manually terminated
• Provides detailed logging for development debugging

Production Server

Starts the Medusa server in production mode for deployment scenarios.

medusa start

Options:

• -H, --host <string>: Set server host (default: localhost)
• -p, --port <string>: Set server port (default: 9000 or PORT environment variable)

Usage Examples:

# Start production server
medusa start

# Start on all interfaces
medusa start --host 0.0.0.0

# Start with custom port
medusa start --port 4000

Behavior:

• Runs in production mode without file watching
• Sets NODE_ENV to 'development' (configurable via environment)
• Optimized for production performance
• Runs indefinitely until manually terminated

Cluster Mode Server (Beta)

Starts the Medusa server in cluster mode for improved performance through process parallelization.

medusa start-cluster

Options:

• -H, --host <string>: Set server host (default: localhost)
• -p, --port <string>: Set server port (default: 9000 or PORT environment variable)
• -c, --cpus <number>: Number of CPU cores to use (default: all available cores or CPUS environment variable)

Usage Examples:

# Start cluster with all available CPUs
medusa start-cluster

# Start cluster with specific CPU count
medusa start-cluster --cpus 4

# Start cluster on custom host and port
medusa start-cluster --host 0.0.0.0 --port 8000 --cpus 2

Behavior:

• Spawns multiple worker processes based on CPU count
• Load balances requests across worker processes
• Enhanced performance for high-traffic scenarios
• Beta feature with ongoing development

Server Configuration

Host and Port Settings

All server commands support flexible host and port configuration:

Host Configuration:

• Default: localhost for local development
• Custom: Any valid hostname or IP address
• Common: 0.0.0.0 for external access

Port Configuration:

• Default: 9000 unless PORT environment variable is set
• Priority: Command line option > PORT environment variable > default (9000)
• Range: Any valid port number (typically 1024-65535 for non-root users)

Environment Variables

The server commands respect and set these environment variables:

NODE_ENV:

• Set to 'development' by default if not already configured
• Can be overridden via environment variable
• Affects logging, caching, and performance optimizations

PORT:

• Used as default port if no --port option provided
• Useful for deployment environments like Heroku
• Command-line options take precedence

CPUS (cluster mode only):

• Sets default CPU count for cluster mode
• Command-line --cpus option overrides this value
• Falls back to system CPU count if not specified

Project Context Requirements

These commands are only available when running inside a valid Medusa project:

Detection Criteria:

• Must have package.json in current directory
• package.json must include @medusajs/medusa in dependencies or devDependencies
• Commands are dynamically loaded from local Medusa installation

Error Handling:

• Shows help message if run outside Medusa project
• Provides clear error messages for missing dependencies
• Attempts to resolve commands from local node_modules

Command Proxying

Development server commands are proxied to the local Medusa installation:

Dynamic Loading:

• Commands are loaded from @medusajs/medusa/dist/commands/[command]
• Uses require.resolve to find local installation
• Falls back to help display if commands cannot be loaded

Argument Passing:

• All CLI arguments and options are passed to underlying Medusa commands
• Project information and package manager preferences are automatically included
• Maintains full compatibility with Medusa's native command interface

Process Management

Long-Running Processes

All server commands are designed to run indefinitely:

• Graceful Startup: Comprehensive initialization and error checking
• Signal Handling: Responds to SIGINT (Ctrl+C) and SIGTERM for clean shutdown
• Process Persistence: Continues running until explicitly terminated
• Resource Management: Proper cleanup of resources on shutdown

Development Workflow Integration

The development server integrates with common development workflows:

• File Watching: Automatic detection of code changes in development mode
• Hot Reloading: Server restarts when source files are modified
• Debug Support: Enhanced logging and error reporting in development
• IDE Integration: Compatible with popular development environments