0
# Project Creation
1

2
The Medusa CLI provides comprehensive project creation capabilities, allowing developers to bootstrap new Medusa Commerce projects with automated setup processes including database configuration, environment setup, and dependency installation.
3

4
## Capabilities
5

6
### New Project Command
7

8
Creates a new Medusa project from a starter template with full automated setup.
9

10
```bash { .api }
11
medusa new [root] [starter]
12
```
13

14
**Parameters:**
15
- `root` (optional): Project directory path. Defaults to current directory if not specified
16
- `starter` (optional): Starter template name or Git URL. Defaults to `medusajs/medusa-starter-default`
17

18
**Options:**
19
- `--seed`: Seed the database with sample data after setup
20
- `--y, --useDefaults`: Use default database credentials without interactive prompts
21
- `--skip-db`: Skip database setup entirely
22
- `--skip-migrations`: Skip running database migrations
23
- `--skip-env`: Skip creating .env file with database configuration
24
- `--db-user <string>`: Database username for connection
25
- `--db-database <string>`: Database name to use
26
- `--db-pass <string>`: Database password for connection
27
- `--db-port <number>`: Database port (default: 5432)
28
- `--db-host <string>`: Database host (default: localhost)
29

30
**Usage Examples:**
31

32
```bash
33
# Interactive project creation
34
medusa new
35
# Prompts for project name and starter selection
36

37
# Create project with specific name and default starter
38
medusa new my-store
39

40
# Create with custom starter from GitHub
41
medusa new my-store https://github.com/medusajs/medusa-starter-contentful
42

43
# Create with custom database settings
44
medusa new my-store --db-user admin --db-pass secret --db-host localhost
45

46
# Create project without database setup
47
medusa new my-store --skip-db
48

49
# Create and seed with sample data
50
medusa new my-store --seed
51
```
52

53
### Interactive Setup Process
54

55
When no arguments are provided, the CLI enters interactive mode:
56

57
1. **Project Name Prompt**: Asks for project directory name (default: "my-medusa-store")
58
2. **Starter Selection**: Choose from predefined starters or specify custom URL:
59
   - `medusa-starter-default` (default option)
60
   - `(Use a different starter)` for custom URL entry
61
3. **Database Configuration**: Interactive database credential collection with validation
62
4. **Setup Execution**: Automated cloning, installation, and configuration
63

64
**Interactive Prompts:**
65

66
```typescript { .api }
67
// Project creation prompts
68
interface ProjectPrompts {
69
  path: string;           // Project directory name
70
  starter: string;        // Starter template selection
71
}
72

73
// Database credential prompts (when not using defaults)
74
interface DatabasePrompts {
75
  continueWithDefault: "Continue" | "Change credentials" | "Skip database setup";
76
  user?: string;          // Database username
77
  password?: string;      // Database password (hidden input)
78
  port?: number;         // Database port
79
  host?: string;         // Database host
80
}
81
```
82

83
### Database Setup Features
84

85
The project creation process includes sophisticated database management:
86

87
**Automatic Database Creation:**
88
- Creates PostgreSQL database with randomly generated name (format: `medusa-db-{5-character-string}`)
89
- Uses `pg-god` library for database creation
90
- Validates database credentials before proceeding
91
- Handles existing database detection and reuse (skips creation if database exists)
92
- Provides detailed error messages for database creation failures
93

94
**Interactive Credential Collection:**
95
- Prompts for database connection details with default credentials:
96
  - Default user: Current system user or "postgres"
97
  - Default database: "postgres"
98
  - Default password: Empty string
99
  - Default port: 5432
100
  - Default host: "localhost"
101
- Tests credentials before proceeding with setup using PostgreSQL connection
102
- Provides three options: Continue, Change credentials, or Skip database setup
103
- Retries credential collection on connection failure
104
- Password input is masked for security
105

106
**Environment Configuration:**
107
- Renames `.env.template` to `.env` if template exists
108
- Automatically creates .env file with `DATABASE_URL` configuration
109
- Generates appropriate connection strings:
110
  - Authenticated: `postgres://user:password@host:port/database`
111
  - Local/No auth: `postgres://host:port/database`
112
- Appends database URL to existing .env content
113
- Supports custom database connection strings
114

115
### Project Initialization Steps
116

117
The CLI executes these steps during project creation:
118

119
1. **Path Validation**: Validates project path and checks for existing Node.js projects
120
2. **Template Acquisition**: 
121
   - Clone from Git repository using `hosted-git-info` for URL parsing
122
   - Copy from local file system path if not a Git URL
123
   - Handle SSH and HTTPS Git protocols automatically
124
3. **Dependency Installation**: 
125
   - Auto-detect npm vs yarn based on `npm_config_user_agent` and lock files
126
   - Store package manager preference for future use
127
   - Install dependencies using detected package manager
128
4. **Database Setup** (if not skipped):
129
   - Interactive credential collection (unless `--useDefaults` specified)
130
   - Create database with randomly generated name
131
   - Handle database creation errors gracefully
132
5. **Environment Configuration** (if not skipped):
133
   - Rename `.env.template` to `.env` if exists
134
   - Generate and append `DATABASE_URL` to .env file
135
6. **Migration Execution** (if not skipped):
136
   - Execute migrations using local Medusa CLI installation
137
   - Run `medusa migrations run` in project directory
138
7. **Seeding** (if `--seed` flag provided):
139
   - Execute package.json seed script if available
140
   - Use detected package manager for script execution
141
8. **Project Cleanup**:
142
   - Remove demo files using `clearProject` utility
143
   - Remove cloned `.git` directory
144
   - Initialize new Git repository
145
   - Create initial commit with starter URL reference
146
9. **Final Setup**: Display success message with next steps
147

148
### Supported Starter Templates
149

150
**Default Starters:**
151
- `medusa-starter-default`: Basic Medusa storefront with essential features
152
- Custom starters can be specified via GitHub URLs or local paths
153

154
**Template Sources:**
155
- GitHub repositories (https://github.com/user/repo)
156
- Local file system paths
157
- Medusa official starter collection (medusajs/starter-name format)
158

159
### Error Handling
160

161
The project creation process includes comprehensive error handling:
162

163
**Validation Errors:**
164
- Invalid project paths (using `is-valid-path` validation)
165
- Existing Node.js projects in target directory (package.json detection)
166
- Invalid Git repository URLs (handled by `hosted-git-info`)
167
- Database connection failures (PostgreSQL connection testing)
168
- Invalid starter template names containing "medusa-starter" as project name
169

170
**Specific Error Scenarios:**
171
```typescript { .api }
172
enum PanicId {
173
  InvalidProjectName = "INVALID_PROJECT_NAME",
174
  InvalidPath = "INVALID_PATH", 
175
  AlreadyNodeProject = "ALREADY_NODE_PROJECT"
176
}
177
```
178

179
**Recovery Mechanisms:**
180
- Retry database credential collection on connection failure with user-friendly prompts
181
- Skip database setup option when credentials fail repeatedly
182
- Cleanup of partial installations on critical errors (removes incomplete project files)
183
- Graceful handling of network connectivity issues during Git cloning
184
- Git repository fallback (removes .git and continues) if initial commit fails
185
- Package manager detection fallback (defaults to npm if yarn unavailable)
186

187
### Package Manager Integration
188

189
The CLI automatically detects and integrates with package managers:
190

191
- **Auto-detection**: Identifies npm vs yarn based on lock files and environment
192
- **Preference Storage**: Remembers user's preferred package manager
193
- **Cross-platform Support**: Works with both npm and yarn installation workflows