Storefront Deployment on Cloud

In this guide, learn how to deploy your storefront with your Medusa application on Cloud.

Storefront Deployment Overview#

Medusa allows you to deploy your storefront alongside your Medusa application on Cloud, enabling you to host and manage both backend and frontend in a single platform.

To deploy a storefront with your Medusa application on Cloud, you need a monorepo structure where both the Medusa application and storefront code are in the same repository. Medusa then builds and deploys both the backend and frontend.

Diagram showcasing how a monorepo is deployed on Cloud. A project will hold a Medusa application with a server and admin, and a storefront.

Storefront Deployment Per Environment#

Similar to the Medusa backend, Medusa deploys a storefront for every long-lived and preview environment, based on your plan's limits. This includes the Production environment. This allows you to test and preview changes in isolation.

You don't add a storefront to each environment separately. When you create a project with a storefront or add a storefront to an existing project, Medusa deploys it in all of the project's environments, including Production. Medusa also deploys it in long-lived and preview environments that you create later.

Medusa also automatically configures the necessary settings for each environment, such as URLs, API keys, and Cross-Origin Resource Sharing (CORS) settings, to ensure seamless connectivity between the storefront and Medusa application.

Deploy Storefront with Medusa Application#

To deploy a storefront with your Medusa application on Cloud, you can either:

  1. Create a new project with a monorepo structure that includes both the Medusa application and storefront code.
  2. Add a storefront to an existing project that already has a Medusa application deployed on Cloud.

Unless you create a new project from a starter, you'll need to set up the monorepo structure. Learn how to create the monorepo in the Prerequisites guide.


Storefront Hosting Features#

Cloud's storefront hosting includes the following features:

  1. End-to-end deployment of your commerce application: Host and manage all components of your commerce application, including server, admin, and storefront, in a single platform.
  2. Zero-configuration deployment: Medusa automatically configures your server and storefront settings, including URLs and CORS, to ensure seamless connectivity between the two.
  3. Storefront previews: Medusa creates both backend and storefront previews for GitHub pull requests, automatically configuring preview URLs and settings to connect to the corresponding Medusa preview. This allows you to preview storefront and backend changes together.
  4. Framework agnostic: Deploy storefronts built with popular frameworks like Next.js and Tanstack Start. Refer to the Supported Storefront Frameworks section for the full list of supported frameworks.
  5. Custom domains: Set up custom domains for your storefronts to use branded URLs for your customers.
  6. SSL Certificates: Cloud automatically provisions and renews SSL certificates for your custom domains, ensuring secure connections for your customers.
  7. Environment-specific configurations: Each environment (production, staging, previews) has its own configuration, allowing you to test changes without affecting the live storefront.

Storefront Hosting Pricing#

Storefront deployment is included in your organization's plan at no additional cost, subject to usage limits.

Exceeding these limits may incur Flex Usage charges.


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.
  • Cloud also supports Incremental Static Regeneration (ISR) for Next.js storefronts with revalidation. Learn more in the Next.js ISR Caching section.
  1. SvelteKit v2.40.0+
  2. Tanstack Start v1.132.0+ (React and Solid)

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


Storefront Custom Domain#

By default, storefronts are deployed at the medusajs.site subdomain. The domain prefix is the same as the Medusa application's subdomain. For example, if your Medusa application is at my-store.medusajs.app, your storefront will be at my-store.medusajs.site.

You can also set up a custom domain for your storefront to use a branded URL. For detailed instructions on setting up and managing custom domains for your storefront, refer to the Custom Domains guide.


Storefront Considerations#

The following section covers considerations to keep in mind when deploying your storefront to Cloud.

Framework-Specific Build Command#

When building your storefront before deployment on Cloud, Medusa runs the build command specific to your storefront framework. For example, if you're using Next.js, Medusa runs next build to build your storefront.

So, if you perform any custom commands or manipulation during the build process, Medusa will not run them.

Pre-Configured Deployment Settings#

When deploying your storefront to Cloud, you don't need to add any specific configurations for deployment. For example, you don't need to specify the hosting provider with a Vite plugin in Tanstack Start.

Medusa automatically injects the necessary configurations during the deployment process to ensure your storefront is correctly set up on Cloud.

For Next.js storefronts, this includes the open-next.config.ts file. If your repository has its own open-next.config.ts, Medusa replaces it during the build.

Next.js ISR Caching#

Next.js storefronts on Cloud support Incremental Static Regeneration (ISR), which caches rendered pages and refreshes them periodically or on demand.

Medusa stores ISR pages and cached fetch responses in a persistent cache shared by all instances of your storefront. So, a page that you revalidate every five minutes, such as with export const revalidate = 300, is regenerated once when it becomes stale, not once for every instance that serves it.

The cache works as follows:

  • When a request arrives for a stale page, your storefront serves the cached page and regenerates it in the background. Medusa deduplicates concurrent regenerations of the same page.
  • On-demand revalidation with revalidatePath and revalidateTag clears the cached page for all instances.
  • The cache is scoped to a deployment. After a new deployment, your storefront renders each page again on its first request.
  • Cached pages expire one day after they're generated. Your storefront renders an expired page again on its next request.
Tip: If your backend receives more storefront requests than expected, check that your pages are cacheable. Next.js renders a page on every request, without caching it, if the page reads cookies(), headers(), or searchParams, or if it calls fetch with cache: "no-store".

Fetch Requests in Middleware Aren't Cached

The shared cache only stores fetch responses made while Next.js renders a page or runs a route handler. Next.js runs middleware in middleware.ts before rendering, outside of its data cache. So, Next.js ignores caching options like next: { revalidate } on fetch requests in middleware, and Medusa never stores their responses in the shared cache.

As a result, every request that runs your middleware sends its fetch requests again. This applies to custom routing setups, such as middleware that retrieves regions from your Medusa backend to resolve the country code in the URL.

To reduce the requests your middleware sends:

  • Keep middleware fetch requests to the minimum your routing logic needs, and limit the paths your middleware runs on with the matcher configuration.
  • Move data that doesn't affect routing out of middleware and into your pages or route handlers, where Medusa caches it.
  • Store values your middleware needs on later requests in a cookie, so your middleware only retrieves them on the first request.

Next.js Image Optimization#

Cloud currently does not support Next.js image optimization for storefronts. The image optimization feature that uses the Next.js Image component's automatic optimization capabilities will not function as expected when deployed on Cloud.

If your storefront relies on Next.js image optimization, you should configure an external image optimization service or disable the feature in your Next.js configuration.

Injected Environment Variables#

When deploying your storefront to Cloud, Medusa automatically injects the following environment variables into your storefront's build and runtime process:

So, make sure to use these environment variables in your storefront to connect it to your Medusa backend.

You can also add custom environment variables to your storefront either during the project creation process on Cloud or later via the project settings.

Was this guide helpful?
Ask Bloom
For assistance in your development, use Claude Code Plugins or Docs MCP server in Cursor, VSCode, etc...FAQ
What is Medusa?
How can I create a module?
How can I create a data model?
How do I create a workflow?
How can I extend a data model in the Product Module?
Recipes
How do I build a marketplace with Medusa?
How do I build digital products with Medusa?
How do I build subscription-based purchases with Medusa?
What other recipes are available in the Medusa documentation?
Chat is cleared on refresh
Line break
⇧↵