> ## 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 build

> Learn how to use the medusa build command to build your Medusa project for production.

# medusa build

Build your Medusa project for production deployment.

## Usage

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
medusa build
```

Output:

```bash theme={null}
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:

```bash theme={null}
medusa build --admin-only
```

Output:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
#!/bin/bash

# Install dependencies
yarn install

# Build the application
medusa build

# Run migrations
medusa db:migrate

# Start production server
medusa start
```

### Docker Example

```dockerfile theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
NODE_OPTIONS="--max-old-space-size=4096" medusa build
```

## See Also

* [medusa develop](./develop.mdx) - Development server with hot reload
* [medusa start](./overview.mdx#development--build) - Start production server