medusa develop

Learn how to use the medusa develop command to start a development server.

medusa develop

Start the Medusa development server with automatic file watching and hot reloading.

Usage

medusa develop

Alias:

medusa dev

Description

The medusa develop command starts a development server that watches your file system and automatically restarts or reloads when files change. This is the primary command you’ll use during development.

How It Works

1. Initializes the Medusa container and loads your configuration
2. Forks a child process running medusa start
3. Watches your project files for changes
4. Automatically reloads or restarts the server when files change

File Watching

The development server watches all files in your project except:

• Dot files (files starting with .)
• node_modules/
• dist/
• static/
• private/
• src/admin/
• .medusa/

When a file is created, modified, or removed, the development server automatically reloads.

Hot Module Replacement (HMR)

By default, the development server uses a standard restart approach. If the backend-hmr feature flag is enabled, the server will use Hot Module Replacement for faster reloads without a full restart.

With HMR enabled, you’ll see:

[HMR] Using backend HMR dev server (reload on file change)
[HMR] Watching filesystem to reload dev server on file change

Without HMR:

[Watcher] Using standard dev server (restart on file change)
[Watcher] Watching filesystem to reload dev server on file change

Options

--types

Generate automated types for modules inside the .medusa directory.

medusa develop --types

• Type: boolean
• Default: true

-H, --host

Set the host for the development server.

medusa develop --host 0.0.0.0

• Type: string
• Default: Value of HOST environment variable, if set

-p, --port

Set the port for the development server.

medusa develop --port 8000

• Type: string
• Default: Value of PORT environment variable, or 9000

Examples

Basic Usage

Start the development server on the default port:

medusa develop

Output:

[Watcher] Using standard dev server (restart on file change)
info: Processing... 
info: Starting Medusa...
info: Server is ready on port 9000
[Watcher] Watching filesystem to reload dev server on file change

Custom Port and Host

Start the development server on a custom port and host:

medusa develop --host 0.0.0.0 --port 8000

Disable Type Generation

Start the development server without generating types:

medusa develop --no-types

File Change Example

When you modify a file, you’ll see output like:

[Watcher] modified src/api/routes.ts modified: restarting dev server
info: Stopping server...
info: Server stopped
info: Starting Medusa...
info: Server is ready on port 9000
[Watcher] Reloaded in 1234.56ms

Environment Variables

The development server sets the following environment variables:

• NODE_ENV=development - Automatically set to development mode
• MEDUSA_HMR_ENABLED=true - Set when HMR is enabled

Stopping the Server

To stop the development server, press Ctrl+C in your terminal. The first time you stop the server, you’ll see a message about starring Medusa on GitHub:

┌─────────────────────────────────────────────────────┐
│                                                     │
│     ✨ Thanks for using Medusa. ✨                  │
│                                                     │
│     If you liked it, please consider starring us   │
│     on GitHub                                       │
│     https://medusajs.com/star                       │
│                                                     │
│     Note: you will not see this message again.     │
│                                                     │
└─────────────────────────────────────────────────────┘

Troubleshooting

Port Already in Use

If the default port 9000 is already in use, specify a different port:

medusa develop --port 8000

Server Keeps Restarting

If the server keeps restarting due to programming errors, the development server will continue watching files and allow you to fix the errors without having to re-run the command.

See Also

• medusa start - Start production server
• medusa build - Build for production