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.12.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. If you've created your Medusa application after v2.14.0, it's already set up in a monorepo structure.

To create a monorepo for projects prior to v2.14.0, 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.

Build Scripts#

In a monorepo, Medusa doesn't run the build script of your root package.json file. Instead, it builds your Medusa application and your storefront separately, each targeting only its own package.

So, instead of a root build script, you need:

1. A build script in your Medusa application's package.json file that runs the medusa build command.
2. A build script in your storefront's package.json file that runs the build command, such as next build.

apps/backend/package.json
1{2  "scripts": {3    "build": "medusa build"4    // other scripts...5  }6}

Medusa only builds the target package and the workspace packages it depends on. The other packages of your monorepo don't enter the build process. Learn more about the build process in the Deployments guide.

Root Files Available During the Build (Turborepo)

If you're using turbo, Medusa prunes your monorepo down to the package it's building before installing dependencies. As a result, the build only has access to the following files from the root of your monorepo:

• package.json
• The lockfile
• pnpm-workspace.yaml
• turbo.json
• .gitignore
• .npmrc

Medusa doesn't copy any other root file into the build, along with the packages that the target package doesn't depend on. For example, if a workspace package's tsconfig.json file extends a shared tsconfig.base.json file at the root, the build fails with the following error, even though the build succeeds locally:

Terminal
❯error TS5083: Cannot read file '/tsconfig.base.json'.

To fix this, move the shared file into a workspace package, then add that package as a dependency of your Medusa application or storefront. Medusa then includes the file in the build, since it builds the target package along with the workspace packages it depends on.

This also applies to files that your Medusa application needs at runtime, such as JSON files or fonts. Keep them within your Medusa application, then copy them to the .medusa/server directory as part of your build script. Learn more in the Built Assets documentation.

If you're using nx instead of turbo, Medusa doesn't prune your monorepo, so all root files are available during the build.

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 with Turbo, you must add the packageManager field to your root package.json:

package.json
1{2  "packageManager": "npm@10.9.2"3}

Replace 10.9.2 with your installed npm version (run npm --version to check). Turborepo requires this field when pruning with NPM workspaces. Without it, the build will fail with a Missing 'packageManager' field error.

If you're also 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. v16 is also supported if you're not using a proxy.
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.