From baaee11114c8b3daa7b717284d43ecdadc0374cf Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 8 Jan 2026 17:39:19 +0200 Subject: [PATCH] docs: updates for storefront in cloud (#14491) * docs: updates for storefront in cloud * comment-out pnpm * fix broken link * npm prerequisites * Update www/apps/cloud/app/storefront/page.mdx Co-authored-by: Stevche Radevski * remove global cdn --------- Co-authored-by: Stevche Radevski --- .../app/learn/deployment/general/page.mdx | 3 + www/apps/book/app/learn/deployment/page.mdx | 5 +- www/apps/book/app/learn/installation/page.mdx | 2 +- www/apps/book/generated/edit-dates.mjs | 6 +- www/apps/book/public/llms-full.txt | 87 +++++++- www/apps/cloud/app/comparison/page.mdx | 90 +++++++- .../cloud/app/connect-storefront/page.mdx | 16 +- .../cloud/app/deployments/access/page.mdx | 48 +++-- www/apps/cloud/app/deployments/page.mdx | 50 ++--- .../environment-variables/page.mdx | 36 ++-- .../app/environments/long-lived/page.mdx | 42 ++-- www/apps/cloud/app/environments/page.mdx | 10 +- .../cloud/app/environments/preview/page.mdx | 62 +++--- www/apps/cloud/app/faq/page.mdx | 4 +- www/apps/cloud/app/logs/page.mdx | 33 +-- www/apps/cloud/app/page.mdx | 3 +- www/apps/cloud/app/projects/page.mdx | 123 ++++++----- .../cloud/app/projects/prerequisites/page.mdx | 201 ++++++++++++++++++ www/apps/cloud/app/sign-up/page.mdx | 4 +- www/apps/cloud/app/storefront/page.mdx | 142 +++++++++++++ www/apps/cloud/app/update-medusa/page.mdx | 1 + www/apps/cloud/generated/edit-dates.mjs | 30 +-- www/apps/cloud/generated/sidebar.mjs | 19 +- www/apps/cloud/sidebar.mjs | 12 ++ www/apps/resources/app/deployment/page.mdx | 11 +- .../app/deployment/storefront/vercel/page.mdx | 22 +- www/apps/resources/generated/edit-dates.mjs | 4 +- .../use-medusa-suggestions/suggestions.ts | 9 + 28 files changed, 855 insertions(+), 220 deletions(-) create mode 100644 www/apps/cloud/app/projects/prerequisites/page.mdx create mode 100644 www/apps/cloud/app/storefront/page.mdx diff --git a/www/apps/book/app/learn/deployment/general/page.mdx b/www/apps/book/app/learn/deployment/general/page.mdx index 7192f1ae4a..26458dbd56 100644 --- a/www/apps/book/app/learn/deployment/general/page.mdx +++ b/www/apps/book/app/learn/deployment/general/page.mdx @@ -18,6 +18,9 @@ With Cloud, you also maintain full customization control as you deploy your own - Multiple testing environments. - Preview environments for new PRs. - Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](!cloud!#cloud-features). diff --git a/www/apps/book/app/learn/deployment/page.mdx b/www/apps/book/app/learn/deployment/page.mdx index ac151eb30d..6f9c4a3f77 100644 --- a/www/apps/book/app/learn/deployment/page.mdx +++ b/www/apps/book/app/learn/deployment/page.mdx @@ -10,7 +10,7 @@ In this chapter, you’ll learn the general approach to deploying the Medusa app Want Medusa to manage and maintain your infrastructure? [Sign up and learn more about Cloud](!cloud!) -Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Cloud hosts your server, Admin dashboard, database, and Redis instance. +Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Cloud hosts your server, Admin dashboard, storefront, database, and Redis instance. With Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub: @@ -18,6 +18,9 @@ With Cloud, you maintain full customization control as you deploy your own modul - Multiple testing environments. - Preview environments for new PRs. - Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](!cloud!#cloud-features). diff --git a/www/apps/book/app/learn/installation/page.mdx b/www/apps/book/app/learn/installation/page.mdx index c1615f751e..6ace8f7a6b 100644 --- a/www/apps/book/app/learn/installation/page.mdx +++ b/www/apps/book/app/learn/installation/page.mdx @@ -10,7 +10,7 @@ In this chapter, you'll learn how to install and run a Medusa application. ## Get Started with Cloud -[Cloud](!cloud!) is Medusa's PaaS platform that allows you to deploy and manage production-ready Medusa applications with ease. Benefit from features like zero-configuration deployments, automatic scaling, and GitHub integration to streamline your development workflow. +[Cloud](!cloud!) is Medusa's PaaS platform that allows you to deploy and manage production-ready Medusa applications with ease. Benefit from features like zero-configuration deployments, automatic scaling, storefront hosting, and GitHub integration to streamline your development workflow. [Sign up](http://cloud.medusajs.com/signup) with Cloud and create your first Medusa project in minutes. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 6708f051e3..34b7149a63 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -1,7 +1,7 @@ export const generatedEditDates = { "app/learn/fundamentals/scheduled-jobs/page.mdx": "2025-10-16T09:35:54.393Z", "app/learn/fundamentals/workflows/page.mdx": "2024-12-09T14:45:17.837Z", - "app/learn/deployment/page.mdx": "2025-09-29T10:25:29.915Z", + "app/learn/deployment/page.mdx": "2026-01-08T09:18:35.778Z", "app/learn/page.mdx": "2025-06-27T11:39:15.941Z", "app/learn/fundamentals/modules/commerce-modules/page.mdx": "2025-04-17T08:51:32.723Z", "app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2025-09-15T09:38:18.299Z", @@ -94,9 +94,9 @@ export const generatedEditDates = { "app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2025-09-15T16:02:51.362Z", "app/learn/fundamentals/environment-variables/page.mdx": "2025-11-26T11:05:38.863Z", "app/learn/build/page.mdx": "2025-10-27T09:30:26.957Z", - "app/learn/deployment/general/page.mdx": "2025-12-11T06:45:25.632Z", + "app/learn/deployment/general/page.mdx": "2026-01-08T09:18:20.179Z", "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2025-08-01T14:59:59.501Z", - "app/learn/installation/page.mdx": "2025-12-04T14:30:00.510Z", + "app/learn/installation/page.mdx": "2026-01-08T09:18:46.731Z", "app/learn/fundamentals/data-models/check-constraints/page.mdx": "2025-07-25T13:50:21.065Z", "app/learn/fundamentals/module-links/link/page.mdx": "2025-12-09T13:27:05.446Z", "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-04-17T08:29:10.166Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 3fb877b2df..bffe99fd6e 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -7787,6 +7787,9 @@ With Cloud, you also maintain full customization control as you deploy your own - Multiple testing environments. - Preview environments for new PRs. - Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](https://docs.medusajs.com/cloud#cloud-features/index.html.md). ### Prerequisites @@ -8116,7 +8119,7 @@ In this chapter, you’ll learn the general approach to deploying the Medusa app Want Medusa to manage and maintain your infrastructure? [Sign up and learn more about Cloud](https://docs.medusajs.com/cloud/index.html.md) -Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Cloud hosts your server, Admin dashboard, database, and Redis instance. +Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Cloud hosts your server, Admin dashboard, storefront, database, and Redis instance. With Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub: @@ -8124,6 +8127,9 @@ With Cloud, you maintain full customization control as you deploy your own modul - Multiple testing environments. - Preview environments for new PRs. - Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](https://docs.medusajs.com/cloud#cloud-features/index.html.md). ## Medusa Project Components @@ -26123,7 +26129,7 @@ In this chapter, you'll learn how to install and run a Medusa application. ## Get Started with Cloud -[Cloud](https://docs.medusajs.com/cloud/index.html.md) is Medusa's PaaS platform that allows you to deploy and manage production-ready Medusa applications with ease. Benefit from features like zero-configuration deployments, automatic scaling, and GitHub integration to streamline your development workflow. +[Cloud](https://docs.medusajs.com/cloud/index.html.md) is Medusa's PaaS platform that allows you to deploy and manage production-ready Medusa applications with ease. Benefit from features like zero-configuration deployments, automatic scaling, storefront hosting, and GitHub integration to streamline your development workflow. [Sign up](http://cloud.medusajs.com/signup) with Cloud and create your first Medusa project in minutes. @@ -49676,6 +49682,7 @@ Connection to Redis in module 'workflow-engine-redis' established - [revokeApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/revokeApiKeysWorkflow/index.html.md) - [updateApiKeysWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateApiKeysWorkflow/index.html.md) - [generateResetPasswordTokenWorkflow](https://docs.medusajs.com/references/medusa-workflows/generateResetPasswordTokenWorkflow/index.html.md) +- [setAuthAppMetadataWorkflow](https://docs.medusajs.com/references/medusa-workflows/setAuthAppMetadataWorkflow/index.html.md) - [addShippingMethodToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addShippingMethodToCartWorkflow/index.html.md) - [addToCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/addToCartWorkflow/index.html.md) - [completeCartWorkflow](https://docs.medusajs.com/references/medusa-workflows/completeCartWorkflow/index.html.md) @@ -50101,6 +50108,7 @@ Connection to Redis in module 'workflow-engine-redis' established - [dismissRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissRemoteLinkStep/index.html.md) - [emitEventStep](https://docs.medusajs.com/references/medusa-workflows/steps/emitEventStep/index.html.md) - [getTranslatedLineItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getTranslatedLineItemsStep/index.html.md) +- [getTranslatedShippingOptionsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getTranslatedShippingOptionsStep/index.html.md) - [removeRemoteLinkStep](https://docs.medusajs.com/references/medusa-workflows/steps/removeRemoteLinkStep/index.html.md) - [updateRemoteLinksStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateRemoteLinksStep/index.html.md) - [useQueryGraphStep](https://docs.medusajs.com/references/medusa-workflows/steps/useQueryGraphStep/index.html.md) @@ -50207,6 +50215,7 @@ Connection to Redis in module 'workflow-engine-redis' established - [updateOrderChangesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderChangesStep/index.html.md) - [updateOrderItemsTranslationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderItemsTranslationsStep/index.html.md) - [updateOrderShippingMethodsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsStep/index.html.md) +- [updateOrderShippingMethodsTranslationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrderShippingMethodsTranslationsStep/index.html.md) - [updateOrdersStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateOrdersStep/index.html.md) - [updateReturnItemsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnItemsStep/index.html.md) - [updateReturnsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateReturnsStep/index.html.md) @@ -50255,6 +50264,7 @@ Connection to Redis in module 'workflow-engine-redis' established - [deleteProductTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductTypesStep/index.html.md) - [deleteProductVariantsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductVariantsStep/index.html.md) - [deleteProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteProductsStep/index.html.md) +- [dismissProductVariantsInventoryStep](https://docs.medusajs.com/references/medusa-workflows/steps/dismissProductVariantsInventoryStep/index.html.md) - [generateProductCsvStep](https://docs.medusajs.com/references/medusa-workflows/steps/generateProductCsvStep/index.html.md) - [getAllProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getAllProductsStep/index.html.md) - [getProductsStep](https://docs.medusajs.com/references/medusa-workflows/steps/getProductsStep/index.html.md) @@ -50365,6 +50375,7 @@ to send a reset password email to the user or customer, for example. entity_id, // The identifier of the user or customer. For example, an email address. actor_type, // The type of actor. For example, "customer", "user", or custom. token, // The generated token. + metadata, // Optional custom metadata passed from the request. } ``` @@ -51806,6 +51817,76 @@ The following workflows emit this event when they're executed. These workflows a *** +## Shipping Option Events + +### Summary + +|Event|Description| +|---|---| +|shipping-option.created|Emitted when shipping options are created.| +|shipping-option.updated|Emitted when shipping options are updated.| +|shipping-option.deleted|Emitted when shipping options are deleted.| + +### shipping-option.created + +Emitted when shipping options are created. + +#### Payload + +```ts +{ + id, // The ID of the shipping option +} +``` + +#### Workflows Emitting this Event + +The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references. + +- [createShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionsWorkflow/index.html.md) + +*** + +### shipping-option.updated + +Emitted when shipping options are updated. + +#### Payload + +```ts +{ + id, // The ID of the shipping option +} +``` + +#### Workflows Emitting this Event + +The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references. + +- [updateShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionsWorkflow/index.html.md) + +*** + +### shipping-option.deleted + +Emitted when shipping options are deleted. + +#### Payload + +```ts +{ + id, // The ID of the shipping option +} +``` + +#### Workflows Emitting this Event + +The following workflows emit this event when they're executed. These workflows are executed by Medusa's API routes. You can also view the events emitted by API routes in the [Store](https://docs.medusajs.com/api/store) and [Admin](https://docs.medusajs.com/api/admin) API references. + +- [deleteShippingOptionsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingOptionsWorkflow/index.html.md) + +*** + ## Translation Events ### Summary @@ -123242,6 +123323,7 @@ To learn more about the commerce features that Medusa provides, check out Medusa - [retrieve](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.retrieve/index.html.md) - [update](https://docs.medusajs.com/references/js_sdk/admin/TaxRegion/methods/js_sdk.admin.TaxRegion.update/index.html.md) - [batch](https://docs.medusajs.com/references/js_sdk/admin/Translation/methods/js_sdk.admin.Translation.batch/index.html.md) +- [entities](https://docs.medusajs.com/references/js_sdk/admin/Translation/methods/js_sdk.admin.Translation.entities/index.html.md) - [list](https://docs.medusajs.com/references/js_sdk/admin/Translation/methods/js_sdk.admin.Translation.list/index.html.md) - [settings](https://docs.medusajs.com/references/js_sdk/admin/Translation/methods/js_sdk.admin.Translation.settings/index.html.md) - [statistics](https://docs.medusajs.com/references/js_sdk/admin/Translation/methods/js_sdk.admin.Translation.statistics/index.html.md) @@ -130596,6 +130678,7 @@ Download this reference as an OpenApi YAML file. You can import this file to too - [GET /admin/transaction-groups](https://docs.medusajs.com/api/admin#transaction-groups_gettransactiongroups) - [GET /admin/translations](https://docs.medusajs.com/api/admin#translations_gettranslations) - [POST /admin/translations/batch](https://docs.medusajs.com/api/admin#translations_posttranslationsbatch) +- [GET /admin/translations/entities](https://docs.medusajs.com/api/admin#translations_gettranslationsentities) - [GET /admin/translations/settings](https://docs.medusajs.com/api/admin#translations_gettranslationssettings) - [GET /admin/translations/statistics](https://docs.medusajs.com/api/admin#translations_gettranslationsstatistics) - [POST /admin/uploads](https://docs.medusajs.com/api/admin#uploads_postuploads) diff --git a/www/apps/cloud/app/comparison/page.mdx b/www/apps/cloud/app/comparison/page.mdx index 57677e66a2..6c7a3a9d7e 100644 --- a/www/apps/cloud/app/comparison/page.mdx +++ b/www/apps/cloud/app/comparison/page.mdx @@ -112,6 +112,28 @@ However, before choosing self-hosting, it's important to understand the challeng Offers GitHub integration, preview and staging environments, and push-to-deploy features, enhancing developer experience and productivity. + + + [Storefront](#storefront) + + + Requires separate deployment and manual configuration to connect to the backend. + + + Deploy storefront alongside your backend with zero configuration and automatic environment setup. + + + + + [Email](#email) + + + Requires setting up and managing your own email infrastructure or third-party service. + + + Built-in email sending service with monitoring and domain verification. + + [Data Backup](#data-backup) @@ -162,7 +184,7 @@ When you deploy your Medusa application on Cloud, you deploy it from your own Gi ### Self-Hosting: Manual Configurations -When you **self-host**, you must manually configure the server for production. You also need to configure database connections, event services, locking mechanisms, and other [Infrastructure Modules](!resources!/infrastructure-modules) that your Medusa application may use. +When you **self-host**, you must manually configure the server for production. You also need to configure database connections, storefront hosting, email services, event services, locking mechanisms, and other [Infrastructure Modules](!resources!/infrastructure-modules) that your Medusa application may use. There may also be platform-specific configurations, adding another layer of complexity that will slow down your time to launch. You'll also need to maintain these configurations over time as Medusa updates are released. @@ -172,7 +194,8 @@ On **Cloud**, Medusa offers: - Pre-configured environments optimized for Medusa applications with no configuration required on your end. - Automated setup and management of infrastructure components. -- Integrated services like [PostgreSQL](../database/page.mdx), [Redis](../redis/page.mdx), and [S3](../s3/page.mdx). +Integrated services like [PostgreSQL](../database/page.mdx), [Redis](../redis/page.mdx), [S3](../s3/page.mdx), and [Medusa Emails](../emails/page.mdx) that work out-of-the-box. +- [Storefront deployment](../storefront/page.mdx) alongside your Medusa application with zero configuration and automatic environment setup. All of these features are available out-of-the-box in your Cloud projects. By using Cloud, you can reduce the time and effort required to get your application up and running, allowing you to focus on building and shipping features. @@ -256,7 +279,9 @@ Cloud users benefit from these optimizations without any additional effort or co ### Self-Hosting: Slower Developer Experience -When you **self-host**, you may miss out on features like code previews and push-to-deploy, making it difficult to review and ship changes quickly. You'll also find it challenging to reproduce production issues, as you'll need to set up staging environments manually, adding to the complexity. +When you **self-host**, you may miss out on features like code previews and push-to-deploy, making it difficult to review and ship changes quickly. + +You'll also find it challenging to reproduce production issues, as you'll need to set up staging environments manually, adding to the complexity. ### Cloud: Enhanced Developer Experience @@ -265,11 +290,70 @@ Medusa enhances the developer experience on **Cloud** by providing features like - GitHub integration for [push-to-deploy](../deployments/page.mdx#how-are-deployments-created). - [Preview environments](../environments/preview/page.mdx) to test changes in pull requests before merging. - [Staging environments](../environments/page.mdx) to test new features and reproduce issues in a production-like setting. +- [Storefront deployment](../storefront/page.mdx) alongside your Medusa application with aligned configurations across environments. You can preview changes in your storefront while previewing backend changes. By using Cloud, you streamline your development workflow and reduce the time and effort required to manage and ship features. --- +## Storefront + +### Self-Hosting: Separate Deployment and Manual Configuration + +When you **self-host**, you need to deploy your storefront separately from your Medusa application. This requires: + +- Setting up a separate hosting environment for your frontend in a separate provider like Vercel or Netlify. +- Manually configuring URLs, API keys, and CORS settings to connect the storefront to the backend. +- Managing different deployments for each environment (production, staging, previews), and ensuring they connect to the correct backend instances. +- Setting up SSL certificates and custom domains independently. +- Configuring CDN and performance optimizations manually. + +This separation adds complexity and increases the chances of configuration errors that can affect your application's functionality. Without proper configuration, you may compromise on developer experience as you won't have integrated previews or staging environments. + +### Cloud: End-to-End Deployment with Zero Configuration + +On **Cloud**, Medusa allows you to deploy your [storefront](../storefront/page.mdx) alongside your Medusa application, enabling you to host and manage both backend and frontend in a single platform. Medusa provides: + +- **Zero-configuration deployment**: Automatically configures URLs, API keys, and CORS settings to ensure seamless connectivity between your storefront and backend. +- **Environment-specific storefronts**: Deploys separate storefront instances for production, staging, and preview environments, with each automatically connected to the corresponding backend. +- **Framework agnostic**: [supports various frontend frameworks](../storefront/page.mdx#supported-storefront-frameworks) like Next.js and Tanstack Start. +- **Custom domains and SSL**: Set up custom domains with automatically provisioned and renewed SSL certificates. +- **Global CDN**: Storefronts are served via a global Content Delivery Network, ensuring fast load times for customers worldwide. + +By using Cloud's storefront hosting, you reduce deployment complexity and ensure all components of your commerce application work together seamlessly. You also enhance the developer experience with integrated previews and staging environments. + +--- + +## Email + +### Self-Hosting: Complex Email Infrastructure Setup + +When you **self-host**, sending transactional and marketing emails requires: + +- Setting up and managing your own email infrastructure or integrating a third-party email service provider. +- Manually configuring notification module providers like SendGrid, Mailgun, or AWS SES. +- Managing email authentication records (SPF, DKIM, DMARC) in your DNS settings. +- Monitoring email deliverability, open rates, and bounce rates manually or through separate analytics tools. +- Handling email sending limits and managing costs as your volume grows. +- Troubleshooting delivery issues without built-in monitoring tools. + +This setup requires technical expertise and ongoing maintenance to ensure reliable email delivery. + +### Cloud: Built-in Email Service with Zero Configuration + +On **Cloud**, Medusa provides [Medusa Emails](../emails/page.mdx), a built-in email sending service that works out-of-the-box with zero configuration. Medusa Emails offers: + +- **Instant setup**: Available by default for all Cloud projects without manual configuration or provider setup. +- **Email monitoring**: Track email delivery rates, open rates, click rates, bounce rates, and complaint rates through the Cloud dashboard. +- **Domain verification**: Verify your own email sender domains to send emails from branded addresses. +- **Organization-wide management**: Monitor email activity across all projects in your organization from a centralized dashboard. +- **Detailed email tracking**: View individual email event histories and preview email content as it was sent to recipients. +- **Plan-based limits**: Different sending limits based on your [plan](../pricing/page.mdx), with the flexibility to scale as needed. + +By using Medusa Emails, you eliminate the need to set up and manage email infrastructure, allowing you to focus on building and sending effective email communications to your customers. + +--- + ## Data Backup ### Self-Hosting: Risky if Not Done Properly diff --git a/www/apps/cloud/app/connect-storefront/page.mdx b/www/apps/cloud/app/connect-storefront/page.mdx index 2537cac92e..aab47e0036 100644 --- a/www/apps/cloud/app/connect-storefront/page.mdx +++ b/www/apps/cloud/app/connect-storefront/page.mdx @@ -8,13 +8,19 @@ In this guide, you'll learn how to allow your production storefront to send requ ## Cloud and Storefront Hosting Overview -Cloud only hosts Medusa applications. It doesn't support hosting your storefronts. Instead, you can use hosting providers like [Vercel](https://vercel.com/) to host your storefronts. +Cloud supports hosting your storefront alongside your Medusa backend and admin dashboard when your project is set up in a monorepo structure. This allows you to deploy and manage both backend and frontend on a single platform with zero configuration. -If you're using the [Next.js Starter Storefront](!resources!/nextjs-starter), you can follow the [Deploy to Vercel](!resources!/deployment/storefront/vercel) guide to deploy your storefront. +The [Project Prerequisites](../projects/prerequisites/page.mdx#prerequisites-for-medusa-application-with-storefront) guide explains how to set up your Medusa application and storefront in a monorepo structure. You can then [create a project](../projects/page.mdx) that includes both the Medusa application and storefront code. + +### When to Host Storefront Externally + +If you can't set up your Medusa application and storefront in a monorepo structure, you can host your storefront externally using any hosting provider of your choice, such as Vercel, Netlify, or AWS. + +This guide explains how to configure your externally hosted storefront to communicate with your Medusa backend on Cloud. To send requests from your production storefront, you need to add some configurations both to it and the Medusa application deployed on Cloud. Otherwise, you'll receive an error when trying to send requests from the storefront. -This guide lists the changes to make in your Medusa application and storefront to allow sending requests from the storefront. While the guide uses the Next.js Starter Storefront as an example, the steps are generally similar for any storefront. +The following sections list the changes to make in your Medusa application and storefront to allow sending requests from the storefront. While the guide uses the Next.js Starter Storefront as an example, the steps are generally similar for any storefront. --- @@ -22,8 +28,8 @@ This guide lists the changes to make in your Medusa application and storefront t To allow your production storefront to access your Medusa application on Cloud, you need to set two Cross-Origin Resource Sharing (CORS) environment variables in your Medusa application: -- `STORE_CORS`: The URLs of storefronts that can access your Medusa server's `/store` API routes. This is a comma-separated list of URLs that is typically used as the value of the [http.storeCors](!docs!/learn/configurations/medusa-config#httpstorecors) configuration. -- `AUTH_CORS`: The URLs of the clients (storefront and admin) that can access the Medusa server's `/auth` API routes. This is a comma-separated list of URLs that is typically used as the value of the [http.authCors](!docs!/learn/configurations/medusa-config#httpauthcors) configuration. +- `STORE_CORS`: The URLs of storefronts that can access your Medusa backend's `/store` API routes. This is a comma-separated list of URLs that is typically used as the value of the [http.storeCors](!docs!/learn/configurations/medusa-config#httpstorecors) configuration. +- `AUTH_CORS`: The URLs of the clients (storefront and admin) that can access the Medusa backend's `/auth` API routes. This is a comma-separated list of URLs that is typically used as the value of the [http.authCors](!docs!/learn/configurations/medusa-config#httpauthcors) configuration. For example, if your storefront is hosted at `https://my-storefront.com`, you can [set the following environment variables in your production environment](../environments/environment-variables/page.mdx#add-environment-variables): diff --git a/www/apps/cloud/app/deployments/access/page.mdx b/www/apps/cloud/app/deployments/access/page.mdx index 9c5574d5b5..85a4f616a4 100644 --- a/www/apps/cloud/app/deployments/access/page.mdx +++ b/www/apps/cloud/app/deployments/access/page.mdx @@ -10,11 +10,11 @@ In this guide, you'll learn how to access your Cloud [deployment](../page.mdx) f You can only access a deployment of an [environment](../../environments/page.mdx) once its status is "Live". A live deployment means that your Medusa application is successfully built and is publicly accessible. You can't access previous deployments or deployments that are still in the "Building" or "Failed" status. -You can access the live deployment's Medusa Admin and send requests to its API routes using the deployment's environment URL. +You can access the live deployment's Medusa Admin, send requests to its API routes, and access its storefront (if applicable) using the deployment's environment URL. --- -## Find Environment's URL +## Find Backend and Admin's URL @@ -22,30 +22,22 @@ For preview environments, refer to the [Preview Environments](../../environments -An environment's URL is in the format `.medusajs.app`, where `` is the subdomain you set either when [creating its project](../../projects/page.mdx#create-a-project) or when [creating the environment](../../environments/long-lived/page.mdx#create-a-long-lived-environment). +An environment's backend URL is in the format `.medusajs.app`, where `` is the subdomain you set either when [creating its project](../../projects/page.mdx#create-a-project) or when [creating the environment](../../environments/long-lived/page.mdx#create-a-long-lived-environment). -You can also find the URL of a deployment's environment through the Cloud dashboard: +You can also find the URL of a deployment's backend through the Cloud dashboard: 1. Select a project from the [organization's dashboard](../../organizations/page.mdx#organization-dashboard). -2. In the project's dashboard, find the URL in the environment's card under its name. For example, find the production URL in the Production environment card. You can copy the URL by clicking the copy icon next to it. +2. In the project's dashboard, find the backend URL in the environment's card under the "Backend" title. You can copy the URL by clicking the copy icon next to it. - - -Aside from the subdomain you set when [creating the environment](../../environments/long-lived/page.mdx#create-a-long-lived-environment), Medusa also provides a unique, randomly generated URL for each environment. Both of these URLs point to the same deployment. - - - -![URL of environment in its card under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1750157464/Cloud/CleanShot_2025-06-17_at_13.50.38_2x_nfxy1t.png) +![URL of environment in its card under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791499/Cloud/CleanShot_2026-01-07_at_15.11.24_2x_xj4vwr.png) 3. You can also click on the environment's name to open its dashboard, where you'll find the URL under the environment's name. -![URL of environment in its dashboard under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081257/Cloud/CleanShot_2025-06-16_at_16.40.37_2x_vxupew.png) +![URL of environment in its dashboard under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791582/Cloud/CleanShot_2026-01-07_at_15.12.50_2x_wca8gl.png) ---- +### Access the Deployment's Medusa Admin -## Access the Deployment's Medusa Admin - -To access the Medusa Admin of a live deployment, click on [the environment's URL](#find-environments-url), or navigate to `/app`. For example, if your environment's URL is `my-project.medusajs.app`, navigate to `my-project.medusajs.app/app`. +To access the Medusa Admin of a live deployment, click on [the environment's URL](#find-backend-and-admins-url), or navigate to `/app`. For example, if your environment's URL is `my-project.medusajs.app`, navigate to `my-project.medusajs.app/app`. You can then log in either using: @@ -63,9 +55,9 @@ If you don't see the "Log in with Medusa Cloud" button on the Medusa Admin log i --- -## Send Requests to the Deployment +## Send Requests to the Deployed Medusa Backend -You can send requests to a live deployment's API routes using the deployment's [environment URL](#find-environments-url). +You can send requests to a live deployment's Medusa backend using the deployment's [environment URL](#find-backend-and-admins-url). For example, to check the health of the live deployment, you can send a `GET` request to the `/health` endpoint: @@ -73,7 +65,7 @@ For example, to check the health of the live deployment, you can send a `GET` re curl https://my-project.medusajs.app/health ``` -Where `https://my-project.medusajs.app` is the environment URL of the deployment. +Where `https://my-project.medusajs.app` is the URL of the environment's Medusa backend. --- @@ -82,3 +74,19 @@ Where `https://my-project.medusajs.app` is the environment URL of the deployment Medusa doesn't support SSH access to the server instance of a deployment. However, you can still access the server's [runtime and build logs](../../logs/page.mdx) to debug issues in your application. If this isn't sufficient for your use case, you can contact support to discuss alternatives. + +--- + +## Find Storefront URL + +If you deployed a storefront alongside your Medusa backend, you can access it using the storefront URL. + +By default, storefronts are deployed at the `medusajs.site` subdomain. The domain prefix is the same as the Medusa backend's subdomain. For example, if your backend is at `my-store.medusajs.app`, your storefront will be at `my-store.medusajs.site`. + +You can find the storefront URL: + +1. Select a project from the [organization's dashboard](../../organizations/page.mdx#organization-dashboard). +2. In the project's dashboard, find the storefront URL in the environment's card under the "Storefront" title. You can copy the URL by clicking the copy icon next to it. +3. Click the URL to open the storefront in a new browser tab. + +You can also set up a custom domain for your storefront. Learn more in the [Storefront Custom Domain](../../storefront/page.mdx#storefront-custom-domain) guide. diff --git a/www/apps/cloud/app/deployments/page.mdx b/www/apps/cloud/app/deployments/page.mdx index a47b62a7cd..7b81b1e145 100644 --- a/www/apps/cloud/app/deployments/page.mdx +++ b/www/apps/cloud/app/deployments/page.mdx @@ -11,12 +11,14 @@ In this guide, you'll learn about deployments in Cloud, how they're created, and ## Deployments Overview -Each [environment](../environments/page.mdx) has at least one deployment, which is publicly accessible at the [environment's URL](./access/page.mdx#find-environments-url). +Each [environment](../environments/page.mdx) has at least one deployment, which is publicly accessible at the [environment's URL](./access/page.mdx#find-backend-and-admins-url). A deployment is created from the latest source code of an [environment](../environments/page.mdx)'s branch. An environment can have only one live deployment at a time. The latest deployment of an environment is the live version of that environment, unless you [redeploy a previous deployment](#redeploy-a-deployment). +If you deployed both the Medusa backend and storefront in an environment, each deployment refers to the backend and storefront. The deployment will also show the status of both the backend and storefront. + --- ## How are Deployments Created? @@ -29,6 +31,8 @@ For short-lived preview environments, Medusa creates a new environment and deplo ## Build Process for Deployments +### Medusa Application Only + Before deploying your application on Cloud, Medusa runs the `build` script defined in your project's `package.json` file, which must run the `medusa build` command, among other build steps you may have. For example, your `build` script may look like this: @@ -47,9 +51,17 @@ You can replace `npm run other-build-steps` with the appropriate command for you -### What Gets Deployed? +### Medusa Application with Storefront -Medusa deploys the contents of the `.medusa/server` directory created by the [build process](!docs!/learn/build). It includes the compiled JavaScript files in your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production. +If you're deploying both a Medusa application and a storefront on Cloud, Medusa will run the: + +1. The `build` command defined in the backend's `package.json` file, which must run the `medusa build` command. +2. The build command relevant to the storefront, depending on the framework you're using. For example, if you're using Next.js for your storefront, Medusa will run the `next build` command in the storefront's directory. + - Medusa currently doesn't support custom build scripts for storefronts. + +### What Gets Deployed in the Medusa Application? + +Medusa deploys the contents of the `.medusa/server` directory of the Medusa application. This directory is created by the [build process](!docs!/learn/build). It includes the compiled JavaScript files in your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production. @@ -94,17 +106,10 @@ You can find the deployments for an environment in the project and environment d For example, to find the deployments for the Production environment: 1. [Go to its project's dashboard](../projects/page.mdx#open-project-dashboard). -2. You can go to the latest Production deployment's details by clicking the "Latest Deployment" link in the Production environment card. +2. Click on the "Production" environment card. +3. You'll find the deployments in the "Deployments" table on the environment's dashboard. -![Production environment card in the Cloud dashboard with the "Latest Deployment" link prominently highlighted, providing quick access to view details about the most recent deployment including status, commit information, and deployment logs](https://res.cloudinary.com/dza7lstvk/image/upload/v1750146946/Cloud/CleanShot_2025-06-17_at_10.54.05_2x_ksw4nk.png) - -3. To find a list of all deployments, click on the "Production" environment card to open the environment's dashboard. - - The "Latest update" card shows details about the latest deployment. - - The "Deployments" card shows the list of all previous deployments. - -![Production environment details page with deployment cards highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750151060/Cloud/CleanShot_2025-06-17_at_10.57.49_2x_wqrfzf.png) - -The last step applies to all environments in your project, including custom environments (like Staging) and preview environments. +![Production environment details page with deployment cards highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790909/Cloud/CleanShot_2026-01-07_at_15.01.37_2x_dixi9u.png) --- @@ -115,22 +120,19 @@ You'll often need to check a deployment's details, such as its status, commit in To view a deployment's details: 1. [Go to its project's dashboard](../projects/page.mdx#open-project-dashboard). -2. If you're looking for the latest deployment: - - Click the "Latest Deployment" link in its environment's card. -3. If you're looking for an older deployment: - - Click on its environment's card to open its dashboard. - - In the "Deployments" card, click on the deployment you want to view. +2. Click on the "Deployments" tab. +3. Click on the deployment in the deployments table. This will open the deployment's details page, where you can also see the deployment's commit at the top of the page. On the deployment details page, you'll find: -![Deployment details page with key sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750147821/Cloud/CleanShot_2025-06-17_at_11.08.58_2x_ea1l8s.png) +![Deployment details page with key sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791012/Cloud/CleanShot_2026-01-07_at_15.02.49_2x_aiatds.png) 1. **Commit**: The commit that the deployment was created from. This is the page's title. 2. **Status**: The current [status](#deployment-statuses-and-lifecycle) of the deployment. For example, "Live" or "Build Failed". You can see it next to the "Redeploy" button. 3. **Author**: The GitHub user who pushed the commit that created the deployment. You can see the user name when you hover over the user's avatar. -4. **Build Logs**: This section shows the logs from the build process. They are useful to understand why a deployment failed. Learn more in the [Logs](../logs/page.mdx) guide. +4. **Activity**: This section shows the build logs for the backend and storefront (if applicable). They are useful to understand why a deployment failed. Learn more in the [Logs](../logs/page.mdx) guide. ### Switch Between Deployments @@ -141,7 +143,7 @@ To switch to a different deployment: 1. Click on the deployment's commit at the top of the Cloud dashboard, next to the environment's name. 2. Choose the deployment you want to switch to from the dropdown. -![Deployment switcher at the top of the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1750148493/Cloud/CleanShot_2025-06-17_at_11.20.16_2x_jegncv.png) +![Deployment switcher at the top of the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791120/Cloud/CleanShot_2026-01-07_at_15.05.15_2x_tblb0s.png) This will change the view to the selected deployment and you'll see its details and logs. @@ -244,7 +246,7 @@ If a deployment is stuck at a status like "Building" or "Deploying" for a long t ## Access Live Deployment -Once a deployment's status is "Live", you can access its Medusa Admin and send requests to its API routes. +Once a deployment's status is "Live", you can access its Medusa Admin, send requests to its API routes, and access its storefront (if applicable). Learn more in the [Access Live Deployment](./access/page.mdx) guide. @@ -283,7 +285,7 @@ To redeploy a deployment: 1. [Go to the deployment's details page](#find-deployment-details). 2. Click the "Redeploy" button at the top right of the page. -![Redeploy button highlighted on the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1750156363/Cloud/CleanShot_2025-06-17_at_13.31.17_2x_i6lfit.png) +![Redeploy button highlighted on the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791243/Cloud/CleanShot_2026-01-07_at_15.07.12_2x_popu4f.png) This will trigger the redeployment process for the selected deployment. The deployment will go through [the same lifecycle](#deployment-statuses-and-lifecycle) as a new deployment. @@ -308,7 +310,7 @@ To change the deployment rules for an environment: 3. Click on the "Deployment rules" tab in the sidebar. 4. You'll find a `branch` rule. You can edit it by clicking the icon and choosing "Edit" from the dropdown. -![Deployment rules section in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1750171235/Cloud/CleanShot_2025-06-17_at_17.40.13_2x_v0vn1k.png) +![Deployment rules section in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767791296/Cloud/CleanShot_2026-01-07_at_15.08.11_2x_f3pkm1.png) 5. In the side window that opens, you can change the branch that the environment is connected to. For example, you can change it from `main` to `staging` to create a new deployment every time you push a commit to the `staging` branch. 6. Click "Save" to apply the changes. diff --git a/www/apps/cloud/app/environments/environment-variables/page.mdx b/www/apps/cloud/app/environments/environment-variables/page.mdx index 6c147d9110..619659501a 100644 --- a/www/apps/cloud/app/environments/environment-variables/page.mdx +++ b/www/apps/cloud/app/environments/environment-variables/page.mdx @@ -11,7 +11,7 @@ In this guide, you'll learn how to manage environment variables of long-lived an Environment variables are key-value pairs of sensitive information, such as API keys and credentials. Instead of hardcoding these variables in your codebase, you should store them as environment variables. -You can manage an environment's variables in its "Settings" tab. +You can manage an environment's variables in its "Settings" tab. You can manage environment variables for the environment's Medusa backend and storefront (if applicable). ## Restricted Environment Variable Names @@ -50,7 +50,8 @@ To add environment variables to an environment: 1. In the [environment's dashboard](../long-lived/page.mdx#open-environment-dashboard), click on the "Settings" tab. 2. Choose the "Environment Variables" tab from the sidebar. -3. In the "Add new environment variables" section, there are different ways you can add environment variables: +3. If you deployed both the Medusa backend and storefront in the environment, use the toggle at the top to switch between managing the backend and storefront environment variables. +4. In the "Add new environment variables" section, you can add environment variables either for the backend or storefront. There are different ways you can add environment variables: - **Manually**: - Enter the key and value of the environment variable in the respective fields. - Click the "Add another" button to add another variable. @@ -58,7 +59,7 @@ To add environment variables to an environment: - If you copied environment variables in a `.env` file format, you can paste them directly into the "Key" field. The environment variables will be pre-filled for you. - **Import `.env` file**: - If you have a `.env` file that defines your environment variables, click the "Import .env" button to upload the file. The environment variables will be automatically extracted and added to the list. -4. Once you're done, click the "Save" button to save the environment variables. +5. Once you're done, click the "Save" button to save the environment variables. @@ -66,7 +67,7 @@ After adding the environment variables, you must [redeploy the environment](../l -![Environment variables section in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816071/Cloud/CleanShot_2025-06-13_at_15.00.54_2x_dbdxl4.png) +![Environment variables section in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790401/Cloud/CleanShot_2026-01-07_at_14.53.15_2x_ehzdre.png) --- @@ -76,14 +77,15 @@ To edit an environment variable: 1. In the [environment's dashboard](../long-lived/page.mdx#open-environment-dashboard), click on the "Settings" tab. 2. Choose the "Environment Variables" tab from the sidebar. -3. In the "Environment variables" section, find the variable you want to edit. -4. Click the icon at the variable's right side. -5. Choose "Edit" from the dropdown menu. +3. If you deployed both the Medusa backend and storefront in the environment, use the toggle at the top to switch between managing the backend and storefront environment variables. +4. In the "Environment variables" section, find the variable you want to edit. +5. Click the icon at the variable's right side. +6. Choose "Edit" from the dropdown menu. -![Edit environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816223/Cloud/CleanShot_2025-06-13_at_15.03.21_2x_a38dch.png) +![Edit environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790460/Cloud/CleanShot_2026-01-07_at_14.54.07_2x_xtkek9.png) -6. In the side window that opens, you can edit the variable's key, value, and whether it's sensitive. -7. Once you're done, click the "Save" button. +7. In the side window that opens, you can edit the variable's key, value, and whether it's sensitive. +8. Once you're done, click the "Save" button. @@ -101,9 +103,10 @@ To delete an environment variable: 1. In the [environment's dashboard](../long-lived/page.mdx#open-environment-dashboard), click on the "Settings" tab. 2. Choose the "Environment Variables" tab from the sidebar. -3. In the "Environment variables" section, find the variable you want to delete. -4. Click the icon at the variable's right side. -5. Choose "Delete" from the dropdown menu. +3. If you deployed both the Medusa backend and storefront in the environment, use the toggle at the top to switch between managing the backend and storefront environment variables. +4. In the "Environment variables" section, find the variable you want to delete. +5. Click the icon at the variable's right side. +6. Choose "Delete" from the dropdown menu. @@ -111,7 +114,7 @@ After deleting the environment variable, you must [redeploy the environment](../ -![Delete environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816223/Cloud/CleanShot_2025-06-13_at_15.03.21_2x_a38dch.png) +![Delete environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790460/Cloud/CleanShot_2026-01-07_at_14.54.07_2x_xtkek9.png) --- @@ -123,10 +126,11 @@ To export an environment's variables: 1. In the [environment's dashboard](../long-lived/page.mdx#open-environment-dashboard), click on the "Settings" tab. 2. Choose the "Environment Variables" tab from the sidebar. -3. In the "Environment variables" section, click on the "Export .env" button at the top right of the section. +3. If you deployed both the Medusa backend and storefront in the environment, use the toggle at the top to switch between managing the backend and storefront environment variables. +4. In the "Environment variables" section, click on the "Export .env" button at the top right of the section. A file download will start with the name `env.txt`, which contains the environment variables in `.env` format. You can rename the file to `.env` and use it in your local development. -![Export env button in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816591/Cloud/CleanShot_2025-06-13_at_15.09.37_2x_k5t0nz.png) \ No newline at end of file +![Export env button in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790560/Cloud/CleanShot_2026-01-07_at_14.55.48_2x_ro5bib.png) \ No newline at end of file diff --git a/www/apps/cloud/app/environments/long-lived/page.mdx b/www/apps/cloud/app/environments/long-lived/page.mdx index 1fd8c52f7c..1bccd1c130 100644 --- a/www/apps/cloud/app/environments/long-lived/page.mdx +++ b/www/apps/cloud/app/environments/long-lived/page.mdx @@ -52,10 +52,10 @@ To create a long-lived environment: 1. In the [project's dashboard](../../projects/page.mdx#open-project-dashboard), click on the "Add environment" button at the top right. 2. In the side window that opens: - - Enter the name of the environment. For example, `Staging`. - - Select the branch you want to associate with this environment. For example, `staging`. + - **Environment name**: Enter the name of the environment. For example, `Staging`. + - **Branch**: Select the branch you want to associate with this environment. For example, `staging`. - If you don't see the branch you want to use, refresh the page to load the latest branches from your repository. - - Set the custom subdomain for the environment. All environments are subdomains of `medusajs.app`. So, if you set the subdomain to `staging-my-project`, the environment's URL will be `staging-my-project.medusajs.app`. + - **Custom subdomain**: Set the custom subdomain for the Medusa application (and, subsequently, storefront). Medusa applications are a subdomain of `medusajs.app`, and their storefront is a subdomain of `medusajs.site`. - Refer to the [Subdomain Restrictions](../../projects/page.mdx#subdomain-restrictions) guide for reserved subdomains and restrictions. 3. Once you're done, click the "Create" button. @@ -67,14 +67,14 @@ The created environment will appear in the [project's dashboard](../../projects/ After creating the environment, Medusa will automatically trigger a deployment for the environment using the associated branch (for example, `staging`). This includes: -- Deploying the environment from the associated branch. +- Deploying the Medusa application and storefront (if applicable) from the associated branch. - Setting up the database and resources for the environment. These are different from the resources of other environments. After that, Medusa will automatically deploy the environment whenever you push a new commit to the associated branch. ### Create Medusa Admin User in Environment -After the environment is deployed, you can log in either with: +After the environment is deployed, you can log in to the Medusa Admin either with: 1. Your Cloud account by clicking the "Log in with Medusa Cloud" button. A user will be created in the Medusa application with the same email as your Cloud account. 2. The email and password you set using environment variables. @@ -117,7 +117,7 @@ If you added the initial admin user's email and password environment variables, This will redeploy the environment's live deployment with the new admin user credentials. -![Redeploy button at the top right of the environment's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081204/Cloud/CleanShot_2025-06-16_at_16.39.44_2x_d3yij6.png) +![Redeploy button at the top right of the environment's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787939/Cloud/CleanShot_2026-01-07_at_14.11.56_2x_bw5p1w.png) Then, wait for the deployment to finish. You can check its status in the "Deployments" section. Once it's deployed, you can [access the environment](#access-deployed-environment) using its URL. @@ -143,17 +143,25 @@ To open an environment's dashboard: This will open the environment's dashboard. You can see the environment's name at the top of the Cloud dashboard. -![Environment dashboard with the name at the top left](https://res.cloudinary.com/dza7lstvk/image/upload/v1749813349/Cloud/CleanShot_2025-06-13_at_14.14.32_2x_ttqg3h.png) +![Environment dashboard with the name at the top left](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787987/Cloud/CleanShot_2026-01-07_at_14.12.59_2x_gocehp.png) ### Find Environment Details On the environment's dashboard, you can find the following details: -![Environment dashboard with sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1749814360/Cloud/CleanShot_2025-06-13_at_14.27.24_2x_rhpaga.png) +![Environment dashboard with sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767788225/Cloud/CleanShot_2026-01-07_at_14.14.22_2x_o0at9s.png) -1. **Environment URL**: The URL to access the environment. You can find it below the environment's name. -2. **Environment Status**: The current status of the environment, such as "Live" or "Deploying". You can find it at the top right of the environment's dashboard. -3. **Environment Deployments**: The list of deployments for the environment, including the latest deployment. You can find it in the "Deployments" section of the environment's dashboard. +1. **Environment Medusa Backend URL**: The URL to access the environment. You can find it below the environment's name. +2. **Environment Storefront URL**: The URL to access the environment's storefront. You can find it below the "Storefront" title in the environment's card. +3. **Medusa Application's Deployment Status**: The current status of the latest Medusa application deployment, such as "Live" or "Deploying". You can find it next to the "Backend" title in the environment's card. +4. **Storefront's Deployment Status**: The current status of the latest storefront deployment, such as "Live" or "Deploying". You can find it next to the "Storefront" title in the environment's card. +5. **Environment Deployments**: The list of deployments for the environment, including the latest deployment. You can find it in the "Deployments" section of the environment's dashboard. + + + +Aside from the subdomain you set when [creating the environment](../../environments/long-lived/page.mdx#create-a-long-lived-environment), Medusa also provides a unique, randomly generated URL for each environment. Both of these URLs point to the same deployment. + + ### Switch Environments @@ -164,15 +172,15 @@ To switch to a different environment: 1. Click on the icon next to the environment's name at the top of the Cloud dashboard. 2. Choose the environment you want to switch to from the dropdown. -![Environment switcher dropdown at the top of the dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749815237/Cloud/CleanShot_2025-06-13_at_14.46.54_2x_j4848b.png) +![Environment switcher dropdown at the top of the dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767788275/Cloud/CleanShot_2026-01-07_at_14.17.45_2x_nkemhm.png) This will change the view to the selected environment, and you'll see its details, logs, and settings. --- -## View Environment Logs +## View Environment Build Logs -You can view build and runtime logs for an environment in the "Logs" section of the environment's dashboard. These logs help you debug issues in your application. +You can view runtime logs for an environment in the "Logs" section of the environment's dashboard. These logs help you debug issues in your application. Learn more in the [Logs guide](../../logs/page.mdx). @@ -180,7 +188,7 @@ Learn more in the [Logs guide](../../logs/page.mdx). ## Manage Environment Variables -In the environment's "Settings" tab, you can manage the environment variables for the environment. Environment variables are key-value pairs that store sensitive information, such as API keys, or configurations that your application needs to run. +In the environment's "Settings" tab, you can manage the environment variables for the environment's Medusa application and storefront. Environment variables are key-value pairs that store sensitive information, such as API keys, or configurations that your application needs to run. Learn how to manage environment variables in the [Environment Variables](../environment-variables/page.mdx) guide. @@ -234,6 +242,4 @@ You can delete any environment in your project, except for the Production enviro To delete an environment: 1. In the environment's dashboard, click on the "Settings" tab. -2. Click the "Delete Environment" button. - -![Delete environment button in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816910/Cloud/CleanShot_2025-06-13_at_15.14.50_2x_qm8hfi.png) +2. Click the "Delete" button. diff --git a/www/apps/cloud/app/environments/page.mdx b/www/apps/cloud/app/environments/page.mdx index cdea7e4dd4..d2eb2f8971 100644 --- a/www/apps/cloud/app/environments/page.mdx +++ b/www/apps/cloud/app/environments/page.mdx @@ -10,7 +10,9 @@ In this guide, you'll learn about environments in Cloud, how to create and manag A Cloud project can have multiple environments, each representing a different stage of your application. For example, you can have a Production environment for your live application, and a Staging environment for testing new features. -Each environment has its own resources, such as a database and server instance. By default, a project has at least a Production environment, and you can create custom environments based on your development needs. +Each environment has its own deployed Medusa backend, admin dashboard, and storefront. It also has its own resources, such as a database and server instance. + +By default, a project has at least a Production environment, and you can create custom environments based on your development needs. Environments are useful to test changes in production-like conditions before actually pushing them to production. You can test out new features, bug fixes, and integrations without affecting the live application. @@ -30,6 +32,8 @@ To view a project's environments: 1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization). 2. Click on the project whose environments you want to view. -In the project's dashboard, you'll find a card for every environment in your project. For example, you may have Production, Staging, and Previews cards. +In the project's dashboard, you'll find a card for every long-lived environment in your project. For example, you may have Production and Staging cards. -![Project dashboard showing the environment cards](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081123/Cloud/CleanShot_2025-06-16_at_16.37.50_2x_wgqkws.png) +You'll also find a table listing all the preview environments created for the project below the long-lived environment cards. + +![Project dashboard showing the environment cards](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787582/Cloud/CleanShot_2026-01-07_at_14.06.03_2x_bane7m.png) diff --git a/www/apps/cloud/app/environments/preview/page.mdx b/www/apps/cloud/app/environments/preview/page.mdx index 65bf0b4d9f..0ee6520621 100644 --- a/www/apps/cloud/app/environments/preview/page.mdx +++ b/www/apps/cloud/app/environments/preview/page.mdx @@ -8,6 +8,8 @@ A preview environment is a short-lived Cloud environment that is automatically c Preview environments facilitate testing a PR's changes in a live environment before merging them. They allow you to test changes in an environment that closely resembles the target long-lived environment. +Each preview environment has its own Medusa backend, admin dashboard, and storefront, along with separate resources like a database and server instance. + Learn more about what environments are and their types in the [Environments](../page.mdx) guide. @@ -33,7 +35,7 @@ So, if you're testing scheduled jobs or events, they may not work as expected in To view the preview environments for a project, go to the [project's dashboard](../../projects/page.mdx#open-project-dashboard). You'll see a "Previews" card with all the preview environments for the project. -![Project dashboard with the Previews card highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081308/Cloud/CleanShot_2025-06-16_at_16.41.30_2x_ocwoqf.png) +![Project dashboard with the Previews card highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767788489/Cloud/CleanShot_2026-01-07_at_14.21.14_2x_mhlotb.png) --- @@ -45,7 +47,7 @@ Medusa will automatically create a preview environment for the PR and deploy the You can also view the preview deployment and its status in the comment made on your PR in GitHub. -![Preview environment deployment comment in GitHub PR](https://res.cloudinary.com/dza7lstvk/image/upload/v1749817407/Cloud/CleanShot_2025-06-13_at_15.23.10_2x_rbjorr.png) +![Preview environment deployment comment in GitHub PR](https://res.cloudinary.com/dza7lstvk/image/upload/v1767789702/Cloud/CleanShot_2026-01-07_at_14.41.31_2x_kc2dms.png) --- @@ -70,32 +72,6 @@ This will increase the concurrent previews limit across projects in your organiz --- -## Access Deployed Preview Environment - -Once the preview environment has finished deploying, you can access its Medusa Admin either through the comment in the PR or by clicking the "Preview" button in the [project's dashboard](../../projects/page.mdx#open-project-dashboard). - -![Preview button in the project's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1750158423/Cloud/CleanShot_2025-06-17_at_14.06.41_2x_yaw699.png) - -This will open the preview environment's Medusa Admin in a new tab, where you can test the changes made in the PR. - -To log into the Medusa Admin of the preview environment, use the admin credentials of the Production environment. If you [configured the shared previews settings](#manage-shared-previews-settings) to use a different environment's database, you can log in with the admin credentials of that environment instead. - -You can also [send requests to the preview deployment's API](../../deployments/page.mdx#send-requests-to-the-deployment). - -### Preview URL Format - -Medusa generates the preview environment URL by: - -- Taking the first `42` characters of the PR's branch name. -- Appending a dash (`-`) followed by the project's handle. - - You can find the project's handle in the project dashboard's URL, which is of the format `cloud.medusajs.com/:org_id/projects/:project_handle`. -- Removing unsafe characters. -- Adding the `medusajs.app` subdomain. - -For example, if your PR's branch name is `feat/product-review` and the project's handle is `m1234`, the URL of the deployed preview environment would be `https://featproduct-review-m1234.medusajs.app`. - ---- - ## Open Preview Environment Dashboard Similar to long-lived environments, you can open a preview environment's dashboard to view its details, logs, and edit its settings. @@ -105,9 +81,33 @@ To open a preview environment's dashboard: 1. Go to its [project's dashboard](../../projects/page.mdx#open-project-dashboard). 2. In the "Previews" card, click on the preview environment you want to view. -Then, you can manage the preview environment just like any other long-lived environment, as mentioned throughout this guide. You can [manage its environment variables](../environment-variables/page.mdx) and [import/export its database dump](../../database/page.mdx). +Then, you can manage the preview environment just like any other long-lived environment. You can [manage its environment variables](../environment-variables/page.mdx) and [import/export its database dump](../../database/page.mdx). -![Preview environment dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749817815/Cloud/CleanShot_2025-06-13_at_15.29.58_2x_h9vn34.png) +![Preview environment dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767789877/Cloud/CleanShot_2026-01-07_at_14.44.30_2x_uswpei.png) + +### Access Deployed Preview Environment + +Once the preview environment has finished deploying, you can access its Medusa Admin and storefront (if applicable) from the preview environment's dashboard. You can click on the URL of the backend or storefront to open them in a new tab. + +![Preview button in the project's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767789953/Cloud/CleanShot_2026-01-07_at_14.45.38_2x_bqe8k1.png) + +To log into the Medusa Admin of the preview environment, use the admin credentials of the Production or associated long-lived environment. If you [configured the shared previews settings](#manage-shared-previews-settings) to use a different environment's database, you can log in with the admin credentials of that environment instead. + +You can also [send requests to the preview deployment's API](../../deployments/page.mdx#send-requests-to-the-deployment). + +### Preview URL Format + +Medusa generates the preview environment URL for the Medusa application by: + +- Taking the first `42` characters of the PR's branch name. +- Appending a dash (`-`) followed by the project's handle. + - You can find the project's handle in the project dashboard's URL, which is of the format `cloud.medusajs.com/:org_id/projects/:project_handle`. +- Removing unsafe characters. +- Adding the `medusajs.app` subdomain. + +For example, if your PR's branch name is `feat/product-review` and the project's handle is `m1234`, the URL of the deployed preview environment would be `https://featproduct-review-m1234.medusajs.app`. + +For the storefront, the same format is used, but with a random prefix to ensure uniqueness across all storefronts, and a `medusajs.site` subdomain. For example, the storefront URL could be `https://abc123-featproduct-review-m1234.medusajs.site`. --- @@ -131,7 +131,7 @@ Making changes to the shared settings will affect all preview environments creat -![Previews settings in the project's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749818069/Cloud/CleanShot_2025-06-13_at_15.34.15_2x_zdh3ha.png) +![Previews settings in the project's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1767790182/Cloud/CleanShot_2026-01-07_at_14.49.36_2x_vn8hej.png) --- diff --git a/www/apps/cloud/app/faq/page.mdx b/www/apps/cloud/app/faq/page.mdx index 8199579c2e..05f914a367 100644 --- a/www/apps/cloud/app/faq/page.mdx +++ b/www/apps/cloud/app/faq/page.mdx @@ -16,9 +16,9 @@ You can also contact a [Medusa Expert](https://medusajs.com/experts/) to help yo ## Does Medusa support hosting storefronts on Cloud? -Medusa can only host Medusa servers and admin dashboards. To host your storefront, you can use hosting providers like Vercel. +Yes, Medusa Cloud supports hosting storefronts alongside your Medusa backend and admin dashboard in a monorepo structure. Cloud supports storefronts built with Next.js, SvelteKit, and Tanstack Start, with automatic configuration and deployment for each environment. -Learn more in the [Connect Production Storefront](../connect-storefront/page.mdx) guide. +Refer to the [Create Project](../projects/page.mdx) to learn more. --- diff --git a/www/apps/cloud/app/logs/page.mdx b/www/apps/cloud/app/logs/page.mdx index acd95957ef..c4b34f5a88 100644 --- a/www/apps/cloud/app/logs/page.mdx +++ b/www/apps/cloud/app/logs/page.mdx @@ -37,37 +37,42 @@ To view the build logs for a deployment: 1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization). 2. Click on the project that the deployment belongs to. 3. Click on the environment that the deployment belongs to, such as "Production". -4. Under the "Deployments" section, find the deployment you want to view the build logs for and click on it. +4. In the "Deployments" table, find the deployment you want to view the build logs for and click on it. -This will open the deployment details page, where you can see the build logs. The build logs are updated in real time as the build process runs, so you can see the progress and any errors that occur during the build. +This will open the deployment details page, where you can see the deployment's activity: -![Build Logs for a deployment](https://res.cloudinary.com/dza7lstvk/image/upload/v1750248493/Cloud/CleanShot_2025-06-18_at_15.07.29_2x_i9ztnt.png) +- **Backend build logs**: Logs for building the Medusa backend. +- **Storefront build logs**: If you deployed a storefront alongside the Medusa application, this shows the logs for building the storefront. + +The build logs are updated in real time as the build process runs, so you can see the progress and any errors that occur during the build. + +![Build Logs for a deployment](https://res.cloudinary.com/dza7lstvk/image/upload/v1767862882/Cloud/CleanShot_2026-01-08_at_11.01.17_2x_x5mfvn.png) ### Search Build Logs on Cloud -You can search the build logs using the search bar at the top right of the "Build logs" section. This is useful for finding specific messages or errors in the logs. +You can search the build logs (for backend and storefront) using the search bar at the top right of the logs. This is useful for finding specific messages or errors in the logs. For example, you can search for keywords like "error" or "warning" to quickly locate issues in the build process. -When you enter the search term, you'll see how many results match your search. You can then move between the results using the up and down arrows next to the search bar. The matching text will be highlighted in the logs. +When you enter the search term, you'll see how the results matching your search. You can move between the results using the up and down arrows next to the search bar. The matching text will be highlighted in the logs. -![Search Build Logs with results highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750316571/Cloud/CleanShot_2025-06-19_at_10.02.36_2x_qzn11c.png) +![Search Build Logs with results highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767863066/Cloud/CleanShot_2026-01-08_at_11.04.21_2x_ldiem6.png) ### Expand and Collapse Build Logs on Cloud Logs for steps in the build process can be expanded or collapsed to improve readability. This is useful when you have many log messages and want to focus on specific parts of the build process. -By default, logs for all steps in the build process are expanded. You can collapse all logs by clicking the "Collapse all" button at the top right of the "Build logs" section. This will hide all the detailed logs and only show the titles of each step. +By default, logs for all steps in the build process are expanded. You can collapse all logs by clicking the "Collapse all" button at the top right of the logs. This will hide all the detailed logs and only show the titles of each step. -![Build logs collapsed](https://res.cloudinary.com/dza7lstvk/image/upload/v1750316687/Cloud/CleanShot_2025-06-19_at_10.04.31_2x_esyfss.png) +![Build logs collapsed](https://res.cloudinary.com/dza7lstvk/image/upload/v1767863208/Cloud/CleanShot_2026-01-08_at_11.06.39_2x_guwi4v.png) You can also expand the logs of all steps in the build process by clicking the "Expand all" button at the top right. This will show all the detailed logs for each step. -![Build logs expanded](https://res.cloudinary.com/dza7lstvk/image/upload/v1750316739/Cloud/CleanShot_2025-06-19_at_10.05.20_2x_ofyfej.png) +![Build logs expanded](https://res.cloudinary.com/dza7lstvk/image/upload/v1767863142/Cloud/CleanShot_2026-01-08_at_11.05.29_2x_epkwit.png) In addition, you can expand or collapse individual steps by clicking the arrow next to a step's title. This gives you more control over which parts of the logs you want to see or hide. -![Build logs with one step collapsed](https://res.cloudinary.com/dza7lstvk/image/upload/v1750316810/Cloud/CleanShot_2025-06-19_at_10.06.36_2x_gfkkzj.png) +![Build logs with one step collapsed](https://res.cloudinary.com/dza7lstvk/image/upload/v1767863176/Cloud/CleanShot_2026-01-08_at_11.06.06_2x_yo9zni.png) ### Pause Build Logs on Cloud @@ -75,21 +80,19 @@ When you view the build logs while the build is still in progress, you can pause To pause the build logs, click the "Pause" button at the bottom right of the page. This button is only shown when there are incoming log messages. When you pause the logs, the button will change to "Resume", allowing you to resume the live log updates. -![Pause button at the bottom right of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1750316962/Cloud/CleanShot_2025-06-19_at_10.08.43_2x_buricw.png) - ### Download Build Logs on Cloud You can download the build logs as a `.log` file for offline analysis, sharing with your team, or sharing with Cloud support if you need help debugging a build issue. -To download build logs, click the button at the top right of the "Build logs" section. This will download the logs in a `.log` file format, which you can open with any text editor. +To download build logs, click the button at the top right of the logs. This will download the logs in a `.log` file format, which you can open with any text editor. -![Download Build Logs button](https://res.cloudinary.com/dza7lstvk/image/upload/v1750317068/Cloud/CleanShot_2025-06-19_at_10.10.52_2x_swbgqj.png) +![Download Build Logs button](https://res.cloudinary.com/dza7lstvk/image/upload/v1767863250/Cloud/CleanShot_2026-01-08_at_11.07.20_2x_yuklfj.png) --- ## View Runtime Logs on Cloud -Runtime logs are useful for debugging the live deployment of an environment, especially when the deployment's status is "Deploy failed". They include logs for: +Runtime logs are useful for debugging the live deployment of an environment's Medusa application, especially when the deployment's status is "Deploy failed". They include logs for: - Errors that occur during application startup. - Errors that occur when handling incoming HTTP requests, such as 404 errors or 500 server errors. diff --git a/www/apps/cloud/app/page.mdx b/www/apps/cloud/app/page.mdx index fc3fa5581b..e76b867c60 100644 --- a/www/apps/cloud/app/page.mdx +++ b/www/apps/cloud/app/page.mdx @@ -4,7 +4,7 @@ export const metadata = { # Cloud Documentation -Medusa allows teams to build and deploy reliable applications quickly without worrying about infrastructure. +Medusa allows teams to build and deploy reliable commerce applications quickly without worrying about infrastructure. Cloud is designed to bridge the gap between development and production, offering features like direct deployments from GitHub, instant preview environments, and more. @@ -19,6 +19,7 @@ Refer to the [Sign Up for Cloud](./sign-up/page.mdx) guide to get started. ## Cloud Features - **Zero Configuration**: Get started with Cloud in minutes without worrying about server configurations, resources management, or scaling. +- **Backend, Admin, and Storefront Hosting**: Host your Medusa backend, admin, and [storefront](./storefront/page.mdx) with Cloud with zero configuration and automatic environment setup. - **Direct deployments from GitHub**: Deploy your Medusa projects directly from your GitHub repository, and trigger deployments automatically on every push to the main branch. - **Multiple Environments**: Create multiple long-lived environments for your projects, such as production and staging, to test changes before going live. - **Instant Preview Environments**: Isolated preview environments are created on every pull request in your repository. diff --git a/www/apps/cloud/app/projects/page.mdx b/www/apps/cloud/app/projects/page.mdx index 762eec480f..451fee0daf 100644 --- a/www/apps/cloud/app/projects/page.mdx +++ b/www/apps/cloud/app/projects/page.mdx @@ -15,6 +15,10 @@ A project is the collection of resources, environments, deployments, and setting To deploy a Medusa application to the Cloud, you create a project for it. Medusa will automatically set up and configure the necessary resources in the project to run the application, such as PostgreSQL, Redis, and S3. +{/* TODO add links */} + +You can deploy either a Medusa application (server and admin dashboard) only, or a Medusa application along with a [storefront](../storefront/page.mdx). + Each project can have multiple environments, such as production and staging. These environments allow you to test changes before pushing them live to users. You can learn more in the [Environments documentation](../environments/page.mdx). --- @@ -29,12 +33,6 @@ If you've reached the limit of projects allowed in your organization's plan, you In this section, you'll learn how to create a project in Cloud to deploy your Medusa application. - - -Make sure your organization's plan supports creating more projects. If you've exceeded the number of projects limit for your plan, contact support to upgrade your plan. - - - To create a project: 1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization). @@ -51,6 +49,8 @@ Medusa provides you with the following starters that you can use to quickly set - **DTC Starter**: Standard Medusa application with fully-fledged commerce features. - **B2B Starter**: Medusa application with powerful B2B and commerce features. +Both starters come with a pre-configured Medusa server, admin dashboard, and Next.js storefront. + To create a project from either of these starters: 1. Click on the **Browse Starters** button at the top right of the [project creation page](#create-a-project). @@ -69,28 +69,7 @@ The repository will be cloned and you'll move forward to the [Configure step](#c If you already have a Medusa application, you can create a project from it. -### Prerequisite: Medusa Application Configurations - -Your existing Medusa application doesn't need specific configurations to be deployed to Cloud. Medusa will automatically: - -- Create the necessary [server and worker instances](!docs!/learn/production/worker-mode). -- Scale your Medusa application's resources based on the traffic it receives. -- Set up and configure production resources and modules for your Medusa application: - - [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis) - - [Redis Event Module](!resources!/infrastructure-modules/event/redis) - - [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis) - - [Redis Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine/redis) - - [S3 File Provider Module](!resources!/infrastructure-modules/file/s3) - -So, 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're expected to manually set up and manage those resources externally and configure them in your Medusa application. - - - -The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module. If you're still using the Cache Module, make sure to remove it from your `medusa-config.ts` file as well. - - - -### Project Creation Steps +Refer to the [Prerequisites for Creating Projects](./prerequisites/page.mdx) guide to ensure your Medusa application meets the necessary prerequisites before deploying it to Cloud. This is especially necessary if you're deploying a storefront along with your Medusa application. To create a project from an existing Medusa application: @@ -108,22 +87,24 @@ You'll move forward to the [Configure step](#configure-project-during-creation). After selecting the repository, you'll move on to the project configuration step. You can set the following information: 1. **Project name**: Enter the name of the project. -2. **Project subdomain**: Enter a custom subdomain for the project. All projects are subdomains of `medusajs.app`. +2. **Custom subdomain**: Enter a custom subdomain for the Medusa application. All projects are subdomains of `medusajs.app`. - For example, if you enter `my-project`, the project will be accessible at `my-project.medusajs.app`. Refer to the [subdomain restrictions](#subdomain-restrictions-for-projects) section for more details. -3. You can expand the "Build details" section to optionally change its configurations: + - If you're hosting a storefront, it will be accessible at `my-project.medusajs.site`. - **Region**: Select a [region](#available-regions-for-projects-in-cloud) to deploy the project. For better performance, choose a region that's closer to your target users. The region can't be changed later. +3. In the **Build details** section, set the following: - **Project root directory**: If your project is in a monorepo, specify the path to the Medusa project in the repository. Otherwise, leave it empty. -4. You can expand the "Environment variables" section to optionally add environment variables: + - **Storefront root directory**: If you're deploying a storefront along with your Medusa application, specify the path to the storefront project in the repository. Otherwise, leave it empty. +4. You can expand the "Initial user" section to optionally set up the credentials of the initial admin user for the Medusa Admin: + - **Email**: The email of the initial admin user. + - **Password**: The password of the initial admin user. +5. You can expand the "Environment variables" section to optionally add environment variables for both backend and storefront: - Enter the key and value for each environment variable you want to add. - Mark the variable as "Sensitive" to hide its value in the UI. - To add more variables, click the "Add another" button. - You can also add and change environment variables later in the project's environment settings. -5. You can expand the "Initial user" section to optionally set up the credentials of the initial admin user for the Medusa Admin: - - **Email**: The email of the initial admin user. - - **Password**: The password of the initial admin user. 6. Once you're done configuring the project, click the "Create" button. -After creating the project, it will take a few minutes to create the necessary resources for it and deploy it. You'll be redirected to the organization dashboard, where you can see the project in the list of projects. +After creating the project, it will take a few minutes to create the necessary resources for it and deploy it. Once the deployment is complete, you'll be able to access the project from your organization's dashboard. @@ -131,13 +112,13 @@ If the project creation takes too long, check out the [troubleshooting section]( -![The organization dashboard with a project in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1749742078/Cloud/CleanShot_2025-06-12_at_18.27.34_2x_voskmq.png) +![The organization dashboard with a project in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1767786136/Cloud/CleanShot_2026-01-07_at_13.42.01_2x_zsdvl6.png) If you click on the project, you'll be taken to the project's dashboard, where you can view [its details and status](#find-project-details). Once the project is created and deployed, you'll receive a notification in the Cloud dashboard. You can also view its status in the list of projects and in the project's details. -![The project status in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1749743107/Cloud/CleanShot_2025-06-12_at_18.40.07_2x_asgpxm.png) +![The project status in the list of projects](https://res.cloudinary.com/dza7lstvk/image/upload/v1767786310/Cloud/CleanShot_2026-01-07_at_13.44.17_2x_cggzib.png) --- @@ -149,7 +130,7 @@ If you encounter any issues while creating a project, [check common deployment i ## Subdomain Restrictions for Projects -Your project's URL must be a subdomain of `medusajs.app`. For example, if you choose `my-store` as your subdomain, your project's URL will be `my-store.medusajs.app`. +Your backend's URL must be a subdomain of `medusajs.app`. For example, if you choose `my-store` as your subdomain, your project's URL will be `my-store.medusajs.app`. When you choose a subdomain for your project, it must be at least five characters long. It also can't be one of the following reserved subdomains: @@ -161,6 +142,8 @@ When you choose a subdomain for your project, it must be at least five character - `development` - `proxy` +If you also deployed a storefront with your Medusa application, its URL will be a subdomain of `medusajs.site`. For example, if your backend's subdomain is `my-store`, your storefront's URL will be `my-store.medusajs.site`. You can also add a custom domain, as explained in the [Storefront Custom Domain](../storefront/page.mdx#storefront-custom-domain) guide. + --- ## Available Regions for Projects in Cloud @@ -177,7 +160,10 @@ All your project's deployments will be in the selected region. For better perfor ## Access Deployed Project -To access the deployed project, you can navigate to the URL of its Production environment. +To access the deployed project, you can navigate to: + +- The Backend URL of the environment. Clicking this URL will open the Medusa Admin in a new tab. +- The Storefront URL of the environment (if you deployed a storefront along with your Medusa application). Clicking this URL will open the storefront in a new tab. Learn more in the [Access Deployment](../deployments/access/page.mdx) guide. @@ -192,22 +178,25 @@ To open a project's dashboard: When you open a project's dashboard, its name will be shown at the top left next to the [organization switcher](../organizations/page.mdx#organization-switcher). -![The project name at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749801071/Cloud/CleanShot_2025-06-13_at_10.50.43_2x_m1snj2.png) +![The project name at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767786526/Cloud/CleanShot_2026-01-07_at_13.48.01_2x_gegnmb.png) ### Find Project Details On the project's dashboard, you can view the following details: -![The project dashboard with the details of a project](https://res.cloudinary.com/dza7lstvk/image/upload/v1759405506/Cloud/CleanShot_2025-10-02_at_14.42.33_2x_w4ql3x.png) +![The project dashboard with the details of a project](https://res.cloudinary.com/dza7lstvk/image/upload/v1767786975/Cloud/CleanShot_2026-01-07_at_13.49.11_2x_f6yppu.png) 1. **Region**: The region where the project is deployed. You'll find it below the project name. -2. **Environments**: The environments for the project are shown as cards. By default, you'll find Production and Previews environments. You can learn more about environments in the [Environments](../environments/page.mdx) guide. +2. **Long-Lived Environments**: The long-lived environments for the project are shown as cards. By default, you'll find the Production environment. You can learn more about environments in the [Environments](../environments/page.mdx) guide. - The Production environment is the live environment where your Medusa application is deployed and clients connect to. - - The Previews environments are created whenever you create a pull request in the linked GitHub repository. They allow you to preview changes before merging them into the main branch. - - Other [Long-lived environments](../environments/long-lived/page.mdx) like Staging will be shown here if you create them. -3. **Production URL**: The URL of the project's production deployment. You'll find it in the "Production" card under the title. Clicking it will open the production Medusa Admin in a new tab. -4. **Repository**: The GitHub repository linked to the project. You'll find it as a "Repository" button at the top right of the project's dashboard. Clicking it will open the repository in a new tab. -5. **Production Deployment Status**: The deployment status of the project's environment, which may be "Live" or "Building". Learn more in the [Deployments](../deployments/page.mdx#deployment-statuses-and-lifecycle) guide. + - Other [Long-lived environments](../environments/long-lived/page.mdx) like Staging will be shown here if you create them. These are useful for testing changes before deploying them to Production. + - Each environment card shows the environment's name, URLs, and status. +3. **Preview Environments**: The Preview environments for the project are shown in a table below the long-lived environments. + - Previews environments are created whenever you create a pull request in the linked GitHub repository. They allow you to preview changes before merging them into the main branch. + - Learn more in the [Preview Environments](../environments/preview/page.mdx) guide. +4. **Production URL**: The URL of the project's production deployment. You'll find the backend and storefront URLs (if deployed) under their respective titles in the Production environment card. +5. **Repository**: The GitHub repository linked to the project. You'll find it as a "Repository" button at the top right of the project's dashboard. Clicking it will open the repository in a new tab. +6. **Production Deployment Status**: The deployment status of the project for the backend and storefront. If it's "Live", then the deployment was successful. Learn more in the [Deployments](../deployments/page.mdx#deployment-statuses-and-lifecycle) guide. ### Switch Projects @@ -218,7 +207,7 @@ To switch to a different project: 1. Click on the icon next to the project's name at the top left of the Cloud dashboard, next to the organization name. 2. Choose the project you want to switch to from the dropdown. -![Project switcher at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749743106/Cloud/CleanShot_2025-06-12_at_18.39.27_2x_imjvkt.png) +![Project switcher at the top left of the Cloud dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787268/Cloud/CleanShot_2026-01-07_at_14.00.01_2x_hylol3.png) This will change the view to the selected project, and you'll see its details, environments, and settings. @@ -232,6 +221,32 @@ Learn more in the [Deployments](../deployments/page.mdx) guide. --- +## Add Storefront to Existing Project + +If you initially created a project with only a Medusa application and later want to add a storefront to it, you can do it from the organization or project's dashboard. + +Before adding a storefront, make sure you've changed your repository structure to a monorepo that includes both the Medusa application and storefront code. Learn how to create the monorepo in the [Prerequisites for Creating Projects](./prerequisites/page.mdx#prerequisites-for-medusa-application-with-storefront) guide. + +Then, to add a storefront to an existing project: + +1. Open the project's dashboard. +2. Click on the "Add storefront" button at the Production environment card. + +![The Add storefront button at the Production environment card](https://res.cloudinary.com/dza7lstvk/image/upload/v1767859152/Cloud/CleanShot_2026-01-08_at_09.58.56_2x_nuqs8s.png) + +3. In the "Add Storefront" form, enter the following details: + - **Storefront root directory**: The path to the storefront project in the repository. + - **Environment variables**: (Optional) Expand this section to add any necessary environment variables. +4. Once you're done, click the "Create" button. + +![Form to add a storefront to an existing project](https://res.cloudinary.com/dza7lstvk/image/upload/v1767859257/Cloud/CleanShot_2026-01-08_at_10.00.52_2x_j2t5mp.png) + +Cloud will then deploy the storefront along with the Medusa application. Once the deployment is complete, you'll be able to access the storefront from the Production environment card in the project's dashboard. + +You can also set a custom domain for the storefront, as explained in the [Storefront](../storefront/page.mdx#storefront-custom-domain) guide. + +--- + ## Edit Project Details After creating a project, you can edit its general details, such as the project name and root directory in the repository, and manage its preview settings. @@ -240,11 +255,11 @@ To edit a project's general details: 1. Open the project's dashboard. 2. Click on the "Settings" tab. -3. In the "General" tab of the Settings page, you can edit the project's name and root directory in the repository. - - Editing the root directory in the repository is useful if the repository is a monorepo. +3. In the "General" tab of the Settings page, you can edit the project's name and root directories of the backend and storefront in the repository. + - Changing the root directory is useful if the structure of your repository has changed. 4. Once you're done making changes, click the "Save changes" button next to the input field. -![The project settings with the General tab selected](https://res.cloudinary.com/dza7lstvk/image/upload/v1749744080/Cloud/CleanShot_2025-06-12_at_18.58.20_2x_gzis0n.png) +![The project settings with the General tab selected](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787375/Cloud/CleanShot_2026-01-07_at_14.02.50_2x_gr7a9r.png) ### Editing Previews Settings @@ -265,7 +280,7 @@ To delete a project: 1. Open the project's dashboard. 2. Click on the "Settings" tab. -3. In the "General" tab of the Settings page, click the "Delete Project" button. -4. Confirm the deletion by typing the project's name in the confirmation input, then click the "Delete" button. +3. In the "General" tab of the Settings page, click the "Delete" button in the "Delete project" section at the bottom. +4. Confirm the deletion by typing "delete project" in the confirmation input, then click the "Delete" button. -![The project settings with the General tab selected and the Delete project section highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1749744219/Cloud/CleanShot_2025-06-12_at_19.03.10_2x_p6lttt.png) +![The project settings with the General tab selected and the Delete project section highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787425/Cloud/CleanShot_2026-01-07_at_14.03.28_2x_b6wkxb.png) diff --git a/www/apps/cloud/app/projects/prerequisites/page.mdx b/www/apps/cloud/app/projects/prerequisites/page.mdx new file mode 100644 index 0000000000..4608f7d581 --- /dev/null +++ b/www/apps/cloud/app/projects/prerequisites/page.mdx @@ -0,0 +1,201 @@ +export const metadata = { + title: `Prerequisites for New Projects`, +} + +# {metadata.title} + +In this guide, learn about the prerequisites for your Medusa application and storefront before deploying it to Medusa Cloud in a new project. + +Alternatively, you can create a project from a starter, as explained in the [Create Projects](../page.mdx) guide. + +## Who is this guide for? + +This guide is intended for developers and teams deploying their local Medusa applications to Medusa 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 Only + +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](#prerequisites-for-medusa-application-with-storefront) for additional prerequisites. + +### Configurations Managed by Medusa 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](!docs!/learn/production/worker-mode). +- 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](!resources!/infrastructure-modules/caching/providers/redis) + - [Redis Event Module](!resources!/infrastructure-modules/event/redis) + - [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis) + - [Redis Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine/redis) + - [S3 File Provider Module](!resources!/infrastructure-modules/file/s3) + +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. + + + +The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module. If you're still using the Cache Module, make sure to remove it from your `medusa-config.ts` file as well. + + + +--- + +## 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](#prerequisites-for-medusa-application-only). + + + +Storefront deployment is an experimental feature, and our team is actively working on enhancing it. If you run into any issues, contact support for assistance. + + + +### 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](https://turborepo.com/) or [nx](https://nx.dev/) 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. + +![Diagram showcasing the monorepo structure with Medusa application and storefront as separate packages](https://res.cloudinary.com/dza7lstvk/image/upload/v1766044505/Cloud/storefront-overview_ebmefz.jpg) + +### 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: + +```json title="package.json" +{ + "scripts": { + "build": "turbo run build" + // other scripts... + } +} +``` + +### 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: + +```yaml title=".yarnrc.yml" +nodeLinker: node-modules + +nmHoistingLimits: 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 PNPM Workspaces + +If you're using `pnpm` as your package manager, set up the following configurations in your monorepo. + +First, create the `.npmrc` file in the root of your monorepo with the following content: + +```text title=".npmrc" +auto-install-peers=true +strict-peer-dependencies=false +shared-workspace-lockfile=false +``` + +You set the following configurations: + +1. `auto-install-peers=true`: Ensures that peer dependencies are automatically installed when you install packages, preventing potential issues with missing peer dependencies. +2. `strict-peer-dependencies=false`: Allows more flexibility when resolving peer dependencies, which can be helpful in a monorepo setup. +3. `shared-workspace-lockfile=false`: Ensures that each package in the monorepo can have its own lockfile, which is necessary for Medusa to resolve dependencies correctly. + +Next, create the `pnpm-workspace.yaml` file in the root of your monorepo with the following content: + +```yaml title="pnpm-workspace.yaml" +packages: + - "apps/**" + - "!apps/backend/.medusa/**" +``` + +This configuration specifies the packages that are part of your pnpm workspace. The example above includes all packages under the `apps` directory, except for the `.medusa` directory within the `backend` package. + +Finally, add the `.npmrc` file to your Medusa application's root directory if it doesn't already exist, with the following content: + +```text title="apps/backend/.npmrc" +public-hoist-pattern[]=*@medusajs/* +public-hoist-pattern[]=@tanstack/react-query +public-hoist-pattern[]=react-i18next +public-hoist-pattern[]=react-router-dom +``` + +This configuration ensures that specific dependencies are hoisted to the root `node_modules` directory, which is necessary for Medusa to function correctly. */} + +### Prerequisites for NPM Workspaces + +If you're using `npm` as your package manager, and you're using the [Next.js Starter Storefront](!resources!/nextjs-starter) as your storefront, add the following override in the storefront's `package.json`: + +```json title="apps/storefront/package.json" +{ + "overrides": { + // other overrides... + "@medusajs/icons": { + "react": "19.0.3", + "react-dom": "19.0.3" + } + } +} +``` + +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`: + +```json title="package.json" +{ + "overrides": { + // other overrides... + "react": "19.0.3", + "react-dom": "19.0.3" + } +} +``` + +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](https://nextjs.org/) v15+ +2. [SvelteKit](https://kit.svelte.dev/) v2.40.0+ +3. [Tanstack Start](https://tanstack.com/start) v1.132.0+ + +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](../../storefront/page.mdx) 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](../page.mdx) guide to learn how to create a new project on Cloud. \ No newline at end of file diff --git a/www/apps/cloud/app/sign-up/page.mdx b/www/apps/cloud/app/sign-up/page.mdx index 6a876bfd4b..1778df2d31 100644 --- a/www/apps/cloud/app/sign-up/page.mdx +++ b/www/apps/cloud/app/sign-up/page.mdx @@ -15,7 +15,7 @@ export const metadata = { In this guide, you'll learn how to sign up for Cloud. You'll create an organization, choose a plan, and set up billing. -After creating an organization, you can start deploying your Medusa applications on Cloud. +After creating an organization, you can start deploying your Medusa applications and storefronts on Cloud. @@ -111,6 +111,6 @@ At this point, Medusa will charge your card for the first month based on the pla Now that you have signed up for Cloud, you can: -- [Create projects](../projects/page.mdx) to deploy your Medusa applications. +- [Create projects](../projects/page.mdx) to deploy your Medusa applications and storefronts. - [Manage your organization](../organizations/page.mdx) settings, including inviting team members. - [Change your plan](../billing/page.mdx#change-your-organizations-plan) or update your payment details. diff --git a/www/apps/cloud/app/storefront/page.mdx b/www/apps/cloud/app/storefront/page.mdx new file mode 100644 index 0000000000..7c16b1c056 --- /dev/null +++ b/www/apps/cloud/app/storefront/page.mdx @@ -0,0 +1,142 @@ +import { CodeTab, CodeTabs } from "docs-ui" + +export const metadata = { + title: `Storefront Deployment on Cloud`, +} + +# {metadata.title} + +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.](https://res.cloudinary.com/dza7lstvk/image/upload/v1766044505/Cloud/storefront-overview_ebmefz.jpg) + +### 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 allows you to test and preview changes in isolation. + +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](../projects/page.mdx#create-a-project) with a monorepo structure that includes both the Medusa application and storefront code. +2. [Add a storefront to an existing project](../projects/page.mdx#add-storefront) 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](../projects/prerequisites/page.mdx#prerequisites-for-medusa-application-with-storefront) 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](#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. +8. **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](../pricing/page.mdx) at no additional cost, subject to usage limits. + +Exceeding these limits may incur [Flex Usage](../usage/page.mdx#what-is-flex-usage) charges. + +--- + +## Supported Storefront Frameworks + +Cloud currently supports deploying storefronts built with the following frameworks: + +1. [Next.js](https://nextjs.org/) v15+ +2. [SvelteKit](https://kit.svelte.dev/) v2.40.0+ +3. [Tanstack Start](https://tanstack.com/start) v1.132.0+ + +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. + +### Prerequisites + +To set up a custom domain for your storefront, you need a domain registered with a domain provider that supports either ALIAS records or top-level CNAME records. + +### Set Up Storefront Custom Domain + +You can set up storefront custom domains per environment. For example, you can set up a custom domain for the Production environment while keeping the default domain for the Staging and preview environments. + +To set up a storefront custom domain for an environment: + +1. Go to a [project's dashboard](../projects/page.mdx#open-project-dashboard) in Cloud. +2. Click on the environment's card where you want to set up the custom domain. For example, the Production environment. +3. In the environment's dashboard, click on the "Settings" tab. +4. Choose the "Storefront Domains" tab from the sidebar. +5. Click on the "Add domain" button. +6. A form with two steps will open: + - **Domain Step**: Enter your custom domain name. For example, `acme.com`. + - **DNS Step**: Follow the instructions to add the necessary DNS records with your domain provider. +7. Once you're done, click the "Done" button. + +Your custom domain will be active once the DNS changes propagate, which may take up to 48 hours. + +--- + +## 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. + +### Injected Environment Variables + +When deploying your storefront to Cloud, Medusa automatically injects the following environment variables into your storefront's build process: + + + + +```shell +NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY # Your Medusa application's publishable key +NEXT_PUBLIC_MEDUSA_BACKEND_URL # Your Medusa backend's URL +MEDUSA_BACKEND_URL # Your Medusa backend's URL, compatible with Next.js Starter Storefront +``` + + + + +```shell +VITE_MEDUSA_PUBLISHABLE_KEY # Your Medusa application's publishable key +VITE_MEDUSA_BACKEND_URL # Your Medusa backend's URL +``` + + + + +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](../environments/environment-variables/page.mdx). diff --git a/www/apps/cloud/app/update-medusa/page.mdx b/www/apps/cloud/app/update-medusa/page.mdx index 5481ab2ae4..8de6c4f083 100644 --- a/www/apps/cloud/app/update-medusa/page.mdx +++ b/www/apps/cloud/app/update-medusa/page.mdx @@ -59,6 +59,7 @@ To update your Medusa application deployed on Cloud: 1. Update your Medusa application locally either on the long-lived environment's branch (for example, Staging) or in a new branch that will be used to create a pull request. - To learn how to update your Medusa application, refer to the [Update guide](!docs!/learn/update). It includes all the details you need to update the Medusa application locally. 2. Once you're done updating your application locally, push the changes in `package.json`, lock file (for example, `yarn.lock`), and any other affected files to the branch. + - If you deployed a storefront alongside your Medusa application, both the backend and storefront will be redeployed when you push changes. - If you're using a long-lived environment, Medusa will automatically deploy the changes to the branch's environment. - If you're using a new branch to create a pull request, open the pull request to the production branch. This will create a preview environment that you can use to test the update before merging it into the production branch. diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs index 4c30614685..18e9c45aaa 100644 --- a/www/apps/cloud/generated/edit-dates.mjs +++ b/www/apps/cloud/generated/edit-dates.mjs @@ -1,33 +1,35 @@ export const generatedEditDates = { - "app/page.mdx": "2025-10-13T10:56:37.352Z", + "app/page.mdx": "2026-01-08T09:12:42.756Z", "app/organization/page.mdx": "2025-06-12T14:43:20.772Z", - "app/projects/page.mdx": "2026-01-06T10:52:09.224Z", - "app/environments/page.mdx": "2025-10-15T15:25:09.940Z", - "app/deployments/page.mdx": "2026-01-06T10:50:49.029Z", + "app/projects/page.mdx": "2026-01-08T08:58:12.499Z", + "app/environments/page.mdx": "2026-01-07T12:07:20.976Z", + "app/deployments/page.mdx": "2026-01-07T13:12:29.617Z", "app/organizations/page.mdx": "2025-12-17T11:56:48.669Z", "app/notifications/page.mdx": "2025-10-15T15:25:33.672Z", "app/database/page.mdx": "2025-10-20T15:47:46.364Z", "app/redis/page.mdx": "2025-10-15T15:22:34.997Z", "app/s3/page.mdx": "2025-10-15T15:23:02.835Z", "app/loyalty-plugin/page.mdx": "2025-10-15T15:27:40.303Z", - "app/logs/page.mdx": "2025-10-15T15:24:53.277Z", - "app/update-medusa/page.mdx": "2026-01-06T10:52:20.587Z", - "app/connect-storefront/page.mdx": "2025-06-25T07:47:00.499Z", - "app/environments/environment-variables/page.mdx": "2025-11-12T15:42:19.187Z", - "app/environments/long-lived/page.mdx": "2026-01-06T10:56:18.660Z", - "app/environments/preview/page.mdx": "2025-11-03T12:50:29.841Z", - "app/faq/page.mdx": "2025-10-08T14:43:21.930Z", + "app/logs/page.mdx": "2026-01-08T09:08:23.867Z", + "app/update-medusa/page.mdx": "2026-01-08T08:54:50.149Z", + "app/connect-storefront/page.mdx": "2026-01-08T08:50:31.830Z", + "app/environments/environment-variables/page.mdx": "2026-01-07T12:56:08.417Z", + "app/environments/long-lived/page.mdx": "2026-01-07T13:10:54.148Z", + "app/environments/preview/page.mdx": "2026-01-07T12:50:13.791Z", + "app/faq/page.mdx": "2026-01-08T08:43:23.224Z", "app/billing/page.mdx": "2025-12-17T12:39:37.397Z", "app/usage/page.mdx": "2025-12-17T13:02:15.554Z", "app/billing/manage/page.mdx": "2025-10-08T14:40:23.629Z", "app/pricing/page.mdx": "2025-09-05T10:31:59.059Z", - "app/sign-up/page.mdx": "2025-11-04T06:51:07.747Z", - "app/comparison/page.mdx": "2025-10-22T14:44:01.898Z", + "app/sign-up/page.mdx": "2026-01-08T08:53:27.044Z", + "app/comparison/page.mdx": "2026-01-08T09:11:35.592Z", "app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z", "app/cache/page.mdx": "2025-11-12T14:37:24.809Z", "app/deployments/troubleshooting/page.mdx": "2025-10-17T14:44:22.894Z", "app/emails/page.mdx": "2025-11-26T11:07:58.083Z", "app/emails/react-email/page.mdx": "2025-11-12T15:41:56.365Z", "app/user/page.mdx": "2025-12-17T12:03:18.968Z", - "app/deployments/access/page.mdx": "2026-01-06T10:56:01.868Z" + "app/deployments/access/page.mdx": "2026-01-08T08:52:48.924Z", + "app/projects/prerequisites/page.mdx": "2026-01-08T08:59:09.732Z", + "app/storefront/page.mdx": "2026-01-08T08:56:47.209Z" } \ No newline at end of file diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs index 5d0b952ad0..7ae40d45a1 100644 --- a/www/apps/cloud/generated/sidebar.mjs +++ b/www/apps/cloud/generated/sidebar.mjs @@ -65,7 +65,16 @@ export const generatedSidebars = [ "type": "link", "title": "Projects", "path": "/projects", - "children": [] + "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Prerequisites", + "path": "/projects/prerequisites", + "children": [] + } + ] }, { "loaded": true, @@ -142,6 +151,14 @@ export const generatedSidebars = [ "title": "Resources", "initialOpen": true, "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Storefront", + "path": "/storefront", + "children": [] + }, { "loaded": true, "isPathHref": true, diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs index ef4cfad7b1..69c504d50f 100644 --- a/www/apps/cloud/sidebar.mjs +++ b/www/apps/cloud/sidebar.mjs @@ -45,6 +45,13 @@ export const sidebar = [ type: "link", title: "Projects", path: "/projects", + children: [ + { + type: "link", + title: "Prerequisites", + path: "/projects/prerequisites", + }, + ], }, { type: "link", @@ -97,6 +104,11 @@ export const sidebar = [ title: "Resources", initialOpen: true, children: [ + { + type: "link", + title: "Storefront", + path: "/storefront", + }, { type: "link", title: "Database", diff --git a/www/apps/resources/app/deployment/page.mdx b/www/apps/resources/app/deployment/page.mdx index 4145b249b8..8b3b3842fb 100644 --- a/www/apps/resources/app/deployment/page.mdx +++ b/www/apps/resources/app/deployment/page.mdx @@ -23,8 +23,11 @@ With Cloud, you maintain full customization control as you deploy your own modul - Multiple testing environments. - Preview environments for new PRs. - Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](!cloud!#cloud-features). -[Sign up and learn more about Cloud](!cloud!). +[Sign up and learn more about Cloud](!cloud!/sign-up). --- @@ -48,6 +51,12 @@ To host and maintain Medusa on your own, check out the following guides. ## Deploy Next.js Starter Storefront + + +Cloud supports deploying storefronts alongside your Medusa application. Learn more in the [Storefront Deployment on Cloud](!cloud!/storefront) guide. + + + Learn how to deploy the Next.js Starter Storefront. + +Cloud supports deploying [storefronts](!cloud!/storefront) alongside your Medusa application with zero-configuration. + +Cloud is our managed services offering that makes deploying and operating Medusa applications possible without having to worry about configuring, scaling, and maintaining infrastructure. Cloud hosts your server, Admin dashboard, storefront, database, and Redis instance. + +With Cloud, you maintain full customization control as you deploy your own modules and customizations directly from GitHub: + +- Push to deploy. +- Multiple testing environments. +- Preview environments for new PRs. +- Test on production-like data. +- Storefront deployment. +- Emails setup. +- [And more](!cloud!#cloud-features). + +[Sign up and learn more about Cloud](!cloud!/sign-up). + + export const medusaSuggestions: Suggestions = new Map([ @@ -42,4 +49,6 @@ export const medusaSuggestions: Suggestions = new Map([ ["minio", CLOUD_S3_SUGGESTION], ["cache", CLOUD_CACHE_SUGGESTION], ["caching", CLOUD_CACHE_SUGGESTION], + ["vercel", CLOUD_STOREFRONT_SUGGESTION], + ["netlify", CLOUD_STOREFRONT_SUGGESTION], ])