Prerequisites for New Projects

In this guide, learn about the prerequisites for your Medusa application and storefront before deploying it to Cloud in a new project.

Alternatively, you can create a project from a starter, as explained in the Create Projects guide.

Who is this guide for?#

This guide is intended for developers and teams deploying their local Medusa applications to Cloud.

You'll learn what setup steps are necessary for:

1. Deploying a Medusa application (server and admin dashboard) only;
2. Or deploying a Medusa application along with a storefront.

Prerequisites for Medusa Application#

This section covers the prerequisites for deploying your Medusa application (server and admin dashboard) to Cloud.

If you're also deploying a storefront with your backend, check the next section for additional prerequisites.

Supported Node.js Versions#

Medusa supports the Node.js LTS of the following major versions:

• 20.x (default)
• 22.x
• 24.x
• 25.x

Specifying Node.js Version

You can override the default Node.js version for your Medusa application by adding an engines field in your package.json file:

package.json
1{2  "engines": {3    "node": ">=22.0.0"4  }5}

Medusa will satisfy this version by the following priority:

1. Find the minimum secure version that matches the range specified in the engines field. For example, if your package.json specifies >=21.0.0, Medusa will use Node.js v22.x since v21.x is no longer supported.
2. If Medusa can't find the minimum secure version that matches the range, it will use the minimum version that satisfies the range, even if it's not an LTS version.
3. If no engines field is specified, Medusa will use the default Node.js version (20.x).

Configurations Managed in Cloud#

Your existing Medusa application (server and admin dashboard) doesn't need specific configurations to be deployed to Cloud. Medusa automatically:

• Creates the necessary server and worker instances.
• Scales your Medusa application's resources based on the traffic it receives.
• Sets up and configures production resources and modules for your Medusa application:
  • Redis Caching Module Provider
  • Redis Event Module
  • Redis Locking Module Provider
  • Redis Workflow Engine Module
  • S3 File Provider Module

Make sure to remove any of these modules from your medusa-config.ts file unless you want to use custom options for them. In that case, you must manually set up and manage those resources externally and configure them in your Medusa application.

Prerequisites for Medusa Application with Storefront#

This section covers the prerequisites for deploying your Medusa application (server and admin dashboard) along with a storefront to Cloud.

Make sure to follow these steps in addition to the ones mentioned in the previous section.

Monorepo Setup#

To deploy your Medusa application along with a storefront, both projects must be set up in a monorepo structure.

To create a monorepo, you need:

1. Package manager: Cloud supports npm, yarn (v1, v3, and v4), and pnpm as package managers.
2. Monorepo tool: You can use turbo or nx to manage your monorepo.

You can structure your monorepo as you see fit. You'll be required to specify the paths to your Medusa application and storefront during the project creation process on Cloud.

Storefront Supported Node.js Versions#

Medusa uses Node.js v24.x (LTS) to build storefronts. You can't override this version.

So, ensure that your storefront is compatible with Node.js v24.x.

Root Build Script#

Your monorepo must have a build script that builds both the Medusa application and the storefront. Medusa executes this script during the deployment process.

For example, if you're using turbo, you should have the following script in your root package.json file:

package.json
1{2  "scripts": {3    "build": "turbo run build"4    // other scripts...5  }6}

Prerequisites for Yarn Workspaces#

If you're using yarn as your package manager, create the .yarnrc.yml file in the root of your monorepo with the following content:

.yarnrc.yml
1nodeLinker: node-modules2
3nmHoistingLimits: workspaces

You set the following configurations:

1. nodeLinker: node-modules: Configures Yarn to install dependencies using the traditional node_modules structure, which is required for Medusa applications.
2. nmHoistingLimits: workspaces: Ensures that dependencies are hoisted only to the workspace level, preventing potential conflicts between packages in the monorepo.

Prerequisites for NPM Workspaces#

If you're using npm as your package manager, and you're using the Next.js Starter Storefront as your storefront, add the following override in the storefront's package.json:

apps/storefront/package.json
1{2  "overrides": {3    // other overrides...4    "@medusajs/icons": {5      "react": "19.0.4",6      "react-dom": "19.0.4"7    }8  }9}

This ensures the @medusajs/icons package uses compatible versions of react and react-dom with the Next.js Starter Storefront.

Also, add the following override in your monorepo's root package.json:

package.json
1{2  "overrides": {3    // other overrides...4    "react": "19.0.4",5    "react-dom": "19.0.4"6  }7}

This ensures that all packages in your monorepo use compatible versions of react and react-dom.

Supported Storefront Frameworks#

Cloud currently supports deploying storefronts built with the following frameworks:

1. Next.js v15
2. SvelteKit v2.40.0+
3. Tanstack Start v1.132.0+ (React and Solid)

If you're using a different framework for your storefront, contact support to request it.

Additional Storefront Considerations#

When deploying your storefront to Cloud, there are additional considerations to keep in mind related to the build process, environment variables, and custom domains.

Refer to the Storefront guide for more details on these considerations.

Next Steps#

Now that you know the prerequisites for deploying your Medusa application and storefront to Cloud, you can create your project.

Refer to the Project guide to learn how to create a new project on Cloud.