Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt

Use this file to discover all available pages before exploring further.

​
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