8.1. Build Medusa Application

In this chapter, you'll learn how to create a production build of your Medusa application for deployment to a hosting provider.

Next chapters explain how to deploy the Medusa application.

Deploy with Cloud: The below instructions are useful for self-hosting your Medusa application. You can also use Cloud to deploy and manage your Medusa application without worrying about infrastructure. Medusa will handle the configurations, deployment, and scaling for you.

build Command#

The Medusa CLI tool provides a build command that creates a standalone build of the Medusa application that:

Doesn't rely on the source TypeScript files.
Can be copied to a production server reliably.

So, to create the production build, run the following command in the root of your Medusa application:

Terminal
❯npx medusa build

Build Output#

The build command creates a .medusa directory in the root of your project that contains your build assets. Do not commit this directory to your repository.

The .medusa directory contains the following subdirectories:

.medusa/server: Contains the production build of your Medusa application.
.medusa/server/public/admin: Contains the production build of the admin dashboard.

Separate Admin Build#

The build command accepts a --admin-only option that outputs the admin to the .medusa/admin directory. This is useful when deploying the admin dashboard separately, such as on Vercel:

Terminal
❯npx medusa build --admin-only

Start Built Medusa Application#

To start the Medusa application after running the build command:

Note: You need to run these steps every time you run the build command, as the .medusa directory is recreated each time.

Change to the .medusa/server directory and install the dependencies:

When running the application locally, make sure to copy the .env file from the root project's directory. In production, use system environment variables instead.

.medusa/server
❯cp ../../.env .env.production

Note: When NODE_ENV=production, the Medusa application loads the environment variables from .env.production. Learn more about environment variables in this guide.

Set NODE_ENV to production in the system environment variable:

Start the Medusa application from .medusa/server:

Authentication Locally in Production Build#

When the Medusa application is started in production (NODE_ENV=production) or staging modes, cookie settings are more strict. You can only use cookie authentication if the client application is served from the same domain as the Medusa server, and the domain is not localhost or part of the public suffix list.

So, if you try to access the Medusa Admin locally in production mode, you won't be able to log in.

To access the Medusa Admin locally in production mode, set the projectConfig.cookieOptions in your medusa-config.ts file to be less strict. For example:

medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    // ...4    cookieOptions: {5      sameSite: "lax",6      secure: false,7    }8  }9})

In this example, you set sameSite to lax and secure to false, which allows cookies to be sent over non-secure connections and from different domains.

Then, rebuild the Medusa application and start it again, as described in the steps above. You can now access the Medusa Admin locally in production mode.

Warning: Make sure to remove the projectConfig.cookieOptions configuration once you're done testing locally, as it's not secure for production environments.

Deploying Production Build#

The next chapter covers how to deploy the production build.

Was this chapter helpful?