Project Creation

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.

Capabilities

New Project Command

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

medusa new [root] [starter]

Parameters:

• root (optional): Project directory path. Defaults to current directory if not specified
• starter (optional): Starter template name or Git URL. Defaults to medusajs/medusa-starter-default

Options:

• --seed: Seed the database with sample data after setup
• --y, --useDefaults: Use default database credentials without interactive prompts
• --skip-db: Skip database setup entirely
• --skip-migrations: Skip running database migrations
• --skip-env: Skip creating .env file with database configuration
• --db-user <string>: Database username for connection
• --db-database <string>: Database name to use
• --db-pass <string>: Database password for connection
• --db-port <number>: Database port (default: 5432)
• --db-host <string>: Database host (default: localhost)

Usage Examples:

# Interactive project creation
medusa new
# Prompts for project name and starter selection

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

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

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

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

# Create and seed with sample data
medusa new my-store --seed

Interactive Setup Process

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

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

Interactive Prompts:

// Project creation prompts
interface ProjectPrompts {
  path: string;           // Project directory name
  starter: string;        // Starter template selection
}

// Database credential prompts (when not using defaults)
interface DatabasePrompts {
  continueWithDefault: "Continue" | "Change credentials" | "Skip database setup";
  user?: string;          // Database username
  password?: string;      // Database password (hidden input)
  port?: number;         // Database port
  host?: string;         // Database host
}

Database Setup Features

The project creation process includes sophisticated database management:

Automatic Database Creation:

• Creates PostgreSQL database with randomly generated name (format: medusa-db-{5-character-string})
• Uses pg-god library for database creation
• Validates database credentials before proceeding
• Handles existing database detection and reuse (skips creation if database exists)
• Provides detailed error messages for database creation failures

Interactive Credential Collection:

• Prompts for database connection details with default credentials:
  • Default user: Current system user or "postgres"
  • Default database: "postgres"
  • Default password: Empty string
  • Default port: 5432
  • Default host: "localhost"
• Tests credentials before proceeding with setup using PostgreSQL connection
• Provides three options: Continue, Change credentials, or Skip database setup
• Retries credential collection on connection failure
• Password input is masked for security

Environment Configuration:

• Renames .env.template to .env if template exists
• Automatically creates .env file with DATABASE_URL configuration
• Generates appropriate connection strings:
  • Authenticated: postgres://user:password@host:port/database
  • Local/No auth: postgres://host:port/database
• Appends database URL to existing .env content
• Supports custom database connection strings

Project Initialization Steps

The CLI executes these steps during project creation:

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

Supported Starter Templates

Default Starters:

• medusa-starter-default: Basic Medusa storefront with essential features
• Custom starters can be specified via GitHub URLs or local paths

Template Sources:

• GitHub repositories (https://github.com/user/repo)
• Local file system paths
• Medusa official starter collection (medusajs/starter-name format)

Error Handling

The project creation process includes comprehensive error handling:

Validation Errors:

• Invalid project paths (using is-valid-path validation)
• Existing Node.js projects in target directory (package.json detection)
• Invalid Git repository URLs (handled by hosted-git-info)
• Database connection failures (PostgreSQL connection testing)
• Invalid starter template names containing "medusa-starter" as project name

Specific Error Scenarios:

enum PanicId {
  InvalidProjectName = "INVALID_PROJECT_NAME",
  InvalidPath = "INVALID_PATH", 
  AlreadyNodeProject = "ALREADY_NODE_PROJECT"
}

Recovery Mechanisms:

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

Package Manager Integration

The CLI automatically detects and integrates with package managers:

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