Skip to main content

​
medusa build

Build your Medusa project for production deployment.

​
Usage

medusa build

​
Description

The medusa build command compiles your Medusa application for production. It performs the following tasks:
  1. Generates TypeScript types for modules
  2. Compiles the backend TypeScript code
  3. Builds the admin dashboard frontend
  4. Outputs compiled files to the appropriate directories
The build process uses the TypeScript configuration from your project’s tsconfig.json file.

​
Options

​
--admin-only

Build only the admin dashboard and skip the backend compilation. 
medusa build --admin-only
  • Type: boolean
  • Default: false
When this flag is set:
  • Only the admin frontend is built
  • Backend code is not compiled
  • Admin is output to .medusa/admin directory
  • Useful when serving the admin separately from the backend

​
Build Process

​
1. Type Generation

The build command first generates automated TypeScript types for your modules. These types are placed in the .medusa directory and provide type safety for your Medusa application.

​
2. Backend Compilation

Unless --admin-only is specified, the build process:
  • Loads your tsconfig.json configuration
  • Compiles all TypeScript files in your project
  • Outputs compiled JavaScript to the dist directory
  • Preserves your project structure in the output

​
3. Admin Dashboard Build

The admin dashboard is built using the Medusa admin bundler:
  • Bundles all admin UI components
  • Optimizes assets for production
  • Outputs to .medusa/admin directory (when using --admin-only) or the standard build directory

​
Examples

​
Standard Build

Build both backend and admin for production: 
medusa build
Output: 
info: Generating types...
info: Types generated successfully
info: Starting build...
info: Compiling backend...
info: Backend compiled successfully
info: Building admin dashboard...
info: Admin dashboard built successfully
info: Build completed

​
Admin-Only Build

Build only the admin dashboard: 
medusa build --admin-only
Output: 
info: Generating types...
info: Types generated successfully
info: Starting build...
info: Building admin dashboard...
info: Admin dashboard built successfully
info: Build completed

​
Build Output

​
Standard Build

After a standard build, your project structure includes: 
your-project/
├── dist/                 # Compiled backend code
│   ├── api/
│   ├── workflows/
│   ├── modules/
│   └── ...
├── .medusa/
│   ├── types/           # Generated TypeScript types
│   └── admin/           # Admin dashboard build (production)
└── ...

​
Admin-Only Build

With --admin-only, only the admin directory is updated: 
your-project/
├── .medusa/
│   └── admin/           # Admin dashboard build
└── ...

​
Build Failures

If the build fails, the command exits with a non-zero exit code: 
medusa build
echo $?  # Will be 1 if build failed, 0 if successful
Common build failures:
  • TypeScript compilation errors: Fix type errors in your code
  • Missing tsconfig.json: Ensure your project has a valid TypeScript configuration
  • Admin bundler errors: Check admin customizations for errors

​
Environment Variables

The build command sets:
  • NODE_ENV=development - Set during the build process (types and compilation use development mode)

​
Integration with Deployment

The build command is typically used in deployment workflows:

​
Example Deployment Script

#!/bin/bash

# Install dependencies
yarn install

# Build the application
medusa build

# Run migrations
medusa db:migrate

# Start production server
medusa start

​
Docker Example

FROM node:20-alpine

WORKDIR /app

COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

COPY . .
RUN medusa build

CMD ["medusa", "start"]

​
Performance Tips

​
Incremental Builds

For faster builds during development, use the development server instead: 
medusa develop
The development server watches files and rebuilds only what changed.

​
Build Caching

When deploying, cache your node_modules and TypeScript build cache to speed up subsequent builds.

​
Troubleshooting

​
”Unable to compile application”

This error occurs when tsconfig.json is missing or invalid: 
error: Unable to compile application
Solution: Ensure you have a valid tsconfig.json in your project root.

​
TypeScript Errors

Build failures due to type errors show detailed error messages: 
error: src/api/routes.ts(10,5): error TS2322: Type 'string' is not assignable to type 'number'
Solution: Fix the TypeScript errors in your code before building.

​
Out of Memory

For large projects, you may need to increase Node.js memory: 
NODE_OPTIONS="--max-old-space-size=4096" medusa build

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us