0
# Development Server Management
1

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

4
## Capabilities
5

6
### Development Server
7

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

10
```bash { .api }
11
medusa develop
12
```
13

14
**Options:**
15
- `-H, --host <string>`: Set server host (default: localhost)
16
- `-p, --port <string>`: Set server port (default: 9000 or PORT environment variable)
17

18
**Usage Examples:**
19

20
```bash
21
# Start development server with defaults
22
medusa develop
23

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

27
# Start with port from environment or custom
28
medusa develop -p 8080
29
```
30

31
**Behavior:**
32
- Enables file watching for automatic server restarts on code changes
33
- Sets NODE_ENV to 'development' if not already set
34
- Runs indefinitely until manually terminated
35
- Provides detailed logging for development debugging
36

37
### Production Server
38

39
Starts the Medusa server in production mode for deployment scenarios.
40

41
```bash { .api }
42
medusa start
43
```
44

45
**Options:**
46
- `-H, --host <string>`: Set server host (default: localhost)
47
- `-p, --port <string>`: Set server port (default: 9000 or PORT environment variable)
48

49
**Usage Examples:**
50

51
```bash
52
# Start production server
53
medusa start
54

55
# Start on all interfaces
56
medusa start --host 0.0.0.0
57

58
# Start with custom port
59
medusa start --port 4000
60
```
61

62
**Behavior:**
63
- Runs in production mode without file watching
64
- Sets NODE_ENV to 'development' (configurable via environment)
65
- Optimized for production performance
66
- Runs indefinitely until manually terminated
67

68
### Cluster Mode Server (Beta)
69

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

72
```bash { .api }
73
medusa start-cluster
74
```
75

76
**Options:**
77
- `-H, --host <string>`: Set server host (default: localhost)
78
- `-p, --port <string>`: Set server port (default: 9000 or PORT environment variable)
79
- `-c, --cpus <number>`: Number of CPU cores to use (default: all available cores or CPUS environment variable)
80

81
**Usage Examples:**
82

83
```bash
84
# Start cluster with all available CPUs
85
medusa start-cluster
86

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

90
# Start cluster on custom host and port
91
medusa start-cluster --host 0.0.0.0 --port 8000 --cpus 2
92
```
93

94
**Behavior:**
95
- Spawns multiple worker processes based on CPU count
96
- Load balances requests across worker processes
97
- Enhanced performance for high-traffic scenarios
98
- Beta feature with ongoing development
99

100
## Server Configuration
101

102
### Host and Port Settings
103

104
All server commands support flexible host and port configuration:
105

106
**Host Configuration:**
107
- Default: `localhost` for local development
108
- Custom: Any valid hostname or IP address
109
- Common: `0.0.0.0` for external access
110

111
**Port Configuration:**
112
- Default: `9000` unless PORT environment variable is set
113
- Priority: Command line option > PORT environment variable > default (9000)
114
- Range: Any valid port number (typically 1024-65535 for non-root users)
115

116
### Environment Variables
117

118
The server commands respect and set these environment variables:
119

120
**NODE_ENV:**
121
- Set to 'development' by default if not already configured
122
- Can be overridden via environment variable
123
- Affects logging, caching, and performance optimizations
124

125
**PORT:**
126
- Used as default port if no --port option provided
127
- Useful for deployment environments like Heroku
128
- Command-line options take precedence
129

130
**CPUS (cluster mode only):**
131
- Sets default CPU count for cluster mode
132
- Command-line --cpus option overrides this value
133
- Falls back to system CPU count if not specified
134

135
## Project Context Requirements
136

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

139
**Detection Criteria:**
140
- Must have package.json in current directory
141
- package.json must include @medusajs/medusa in dependencies or devDependencies
142
- Commands are dynamically loaded from local Medusa installation
143

144
**Error Handling:**
145
- Shows help message if run outside Medusa project
146
- Provides clear error messages for missing dependencies
147
- Attempts to resolve commands from local node_modules
148

149
## Command Proxying
150

151
Development server commands are proxied to the local Medusa installation:
152

153
**Dynamic Loading:**
154
- Commands are loaded from `@medusajs/medusa/dist/commands/[command]`
155
- Uses require.resolve to find local installation
156
- Falls back to help display if commands cannot be loaded
157

158
**Argument Passing:**
159
- All CLI arguments and options are passed to underlying Medusa commands
160
- Project information and package manager preferences are automatically included
161
- Maintains full compatibility with Medusa's native command interface
162

163
## Process Management
164

165
### Long-Running Processes
166

167
All server commands are designed to run indefinitely:
168

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

174
### Development Workflow Integration
175

176
The development server integrates with common development workflows:
177

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