From d97a60d3c1394c07af04fb250899080e274ea73d Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 20 Oct 2025 15:45:11 +0300 Subject: [PATCH] docs: document build output + Cloud troubleshooting (#13774) --- www/apps/book/app/learn/build/page.mdx | 84 +++++++++++++------ www/apps/book/generated/edit-dates.mjs | 2 +- www/apps/book/public/llms-full.txt | 80 ++++++++++++------ www/apps/cloud/app/deployments/page.mdx | 48 ++++++++++- .../app/deployments/troubleshooting/page.mdx | 46 ++++++++++ www/apps/cloud/app/projects/page.mdx | 5 +- www/apps/cloud/generated/edit-dates.mjs | 7 +- www/apps/cloud/generated/sidebar.mjs | 11 ++- www/apps/cloud/sidebar.mjs | 7 ++ 9 files changed, 232 insertions(+), 58 deletions(-) create mode 100644 www/apps/cloud/app/deployments/troubleshooting/page.mdx diff --git a/www/apps/book/app/learn/build/page.mdx b/www/apps/book/app/learn/build/page.mdx index 76ca5c2376..f335559aec 100644 --- a/www/apps/book/app/learn/build/page.mdx +++ b/www/apps/book/app/learn/build/page.mdx @@ -6,7 +6,7 @@ export const metadata = { In this chapter, you'll learn how to create a production build of your Medusa application for deployment to a hosting provider. -Next chapters explain how to deploy the Medusa application. +The next chapter explains how to deploy your Medusa application. @@ -27,24 +27,7 @@ So, to create the production build, run the following command in the root of you npx medusa build ``` ---- - -## Build Output - -The `build` command creates a `.medusa` directory in the root of your project that contains your build assets. Do not commit this directory to your repository. - -The `.medusa` directory contains the following subdirectories: - -- `.medusa/server`: Contains the production build of your Medusa application. -- `.medusa/server/public/admin`: Contains the production build of the admin dashboard. - -### Separate Admin Build - -The `build` command accepts a `--admin-only` option that outputs the admin to the `.medusa/admin` directory. This is useful when deploying the admin dashboard separately, such as on Vercel: - -```bash -npx medusa build --admin-only -``` +The command will create a `.medusa/server` directory in the root of your project that contains your build assets. The next sections explain how to use the build output. --- @@ -54,7 +37,7 @@ To start the Medusa application after running the `build` command: -You need to run these steps every time you run the `build` command, as the `.medusa` directory is recreated each time. +You need to run these steps every time you run the `build` command, since the `.medusa/server` directory is recreated each time. @@ -72,7 +55,7 @@ cp ../../.env .env.production -When `NODE_ENV=production`, the Medusa application loads the environment variables from `.env.production`. Learn more about environment variables in [this guide](../fundamentals/environment-variables/page.mdx). +When `NODE_ENV=production`, the Medusa application loads the environment variables from `.env.production`. Learn more in the [environment variables guide](../fundamentals/environment-variables/page.mdx). @@ -90,9 +73,9 @@ npm run start ### Authentication Locally in Production Build -When the Medusa application is started in production (`NODE_ENV=production`) or staging modes, cookie settings are more strict. You can only use cookie authentication if the client application is served from the same domain as the Medusa server, and the domain is not `localhost` or part of the [public suffix list](https://publicsuffix.org/). +When the Medusa application is started in production (`NODE_ENV=production`) or staging mode, cookie settings are stricter. Cookie authentication only works if the client application is served from the same domain as the Medusa server, and the domain is not `localhost` or part of the [public suffix list](https://publicsuffix.org/). -So, if you try to access the Medusa Admin locally in production mode, you won't be able to log in. +So if you try to access the Medusa Admin locally in production mode, you won't be able to log in. To access the Medusa Admin locally in production mode, set the `projectConfig.cookieOptions` in your `medusa-config.ts` file to be less strict. For example: @@ -110,7 +93,7 @@ module.exports = defineConfig({ In this example, you set `sameSite` to `lax` and `secure` to `false`, which allows cookies to be sent over non-secure connections and from different domains. -Then, rebuild the Medusa application and start it again, as described in the [steps above](#start-built-medusa-application). You can now access the Medusa Admin locally in production mode. +Then rebuild the Medusa application and start it again as described in the [steps above](#start-built-medusa-application). You can now access the Medusa Admin locally in production mode. @@ -120,6 +103,59 @@ Make sure to remove the `projectConfig.cookieOptions` configuration once you're --- +## Build Output + +The `build` command creates a `.medusa/server` directory in the root of your project that contains your build assets. Do not commit this directory to your repository. This directory should be generated as part of your deployment process. + +The `.medusa/server` directory contains the following: + +![.medusa/server directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1760709518/Medusa%20Book/output-dir_dlklk6.jpg) + +- `public/admin`: Contains the production build of the admin dashboard. The `public` directory is publicly accessible. +- `src`: Contains the compiled JavaScript files of your `src` directory. +- `instrumentation.js`: The compiled [instrumentation configuration file](../debugging-and-testing/instrumentation/page.mdx), if you have one. +- `medusa-config.js`: The compiled Medusa configuration file. +- `package.json` and a lock file: The dependencies required to run the Medusa application in production. + +### Built Assets + +The `build` command compiles and copies `.{ts,js,tsx,jsx}` files in your project, such as those in the root directory and in the `src` directory. + +If you have other assets, such as JSON files or fonts, that you need in your Medusa backend at runtime, you need to copy them to the `.medusa/server` directory as part of your build process. + +For example, consider you have a `src/data` directory that contains JSON files needed at runtime. You can add a `postbuild` script to your `package.json` file to copy this directory after the build process: + +```json title="package.json" +{ + "scripts": { + "postbuild": "cp -r src/data .medusa/server/src/data", + "build": "medusa build && npm run postbuild" + } +} +``` + +This script copies the `src/data` directory to the `.medusa/server` directory after the build process. + + + +Do not expose sensitive files in your deployments, especially in the `.medusa/server/public` directory, as they will be publicly accessible. Sensitive files include those containing API keys, database credentials, or any other confidential information. + + + +### Customize Admin Build + +The admin dashboard is built with [Vite](!https://vitejs.dev/). If you need to customize the build process to include additional static assets, you can modify the Vite configuration with the [admin.vite](../configurations/medusa-config/page.mdx) option in your `medusa-config.ts` file. + +### Separate Admin Build + +The `build` command accepts a `--admin-only` option that outputs the admin to the `.medusa/admin` directory. This is useful when deploying the admin dashboard separately, such as on Vercel: + +```bash +npx medusa build --admin-only +``` + +--- + ## Deploying Production Build The next chapter covers how to deploy the production build. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index a7860691c4..5a7ce6aa49 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -93,7 +93,7 @@ export const generatedEditDates = { "app/learn/fundamentals/data-models/infer-type/page.mdx": "2025-03-18T07:41:01.936Z", "app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2025-09-15T16:02:51.362Z", "app/learn/fundamentals/environment-variables/page.mdx": "2025-05-26T15:06:07.800Z", - "app/learn/build/page.mdx": "2025-09-30T06:14:50.101Z", + "app/learn/build/page.mdx": "2025-10-17T14:48:44.767Z", "app/learn/deployment/general/page.mdx": "2025-09-29T10:21:24.768Z", "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2025-08-01T14:59:59.501Z", "app/learn/installation/page.mdx": "2025-07-23T14:28:50.404Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 367d239700..d9fd728d35 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -4,7 +4,7 @@ In this chapter, you'll learn how to create a production build of your Medusa application for deployment to a hosting provider. -Next chapters explain how to deploy the Medusa application. +The next chapter explains how to deploy your Medusa application. The below instructions are useful for self-hosting your Medusa application. You can also use [Cloud](https://docs.medusajs.com/cloud/index.html.md) to deploy and manage your Medusa application without worrying about infrastructure. Medusa will handle the configurations, deployment, and scaling for you. @@ -21,24 +21,7 @@ So, to create the production build, run the following command in the root of you npx medusa build ``` -*** - -## Build Output - -The `build` command creates a `.medusa` directory in the root of your project that contains your build assets. Do not commit this directory to your repository. - -The `.medusa` directory contains the following subdirectories: - -- `.medusa/server`: Contains the production build of your Medusa application. -- `.medusa/server/public/admin`: Contains the production build of the admin dashboard. - -### Separate Admin Build - -The `build` command accepts a `--admin-only` option that outputs the admin to the `.medusa/admin` directory. This is useful when deploying the admin dashboard separately, such as on Vercel: - -```bash -npx medusa build --admin-only -``` +The command will create a `.medusa/server` directory in the root of your project that contains your build assets. The next sections explain how to use the build output. *** @@ -46,7 +29,7 @@ npx medusa build --admin-only To start the Medusa application after running the `build` command: -You need to run these steps every time you run the `build` command, as the `.medusa` directory is recreated each time. +You need to run these steps every time you run the `build` command, since the `.medusa/server` directory is recreated each time. 1. Change to the `.medusa/server` directory and install the dependencies: @@ -60,7 +43,7 @@ cd .medusa/server && npm install cp ../../.env .env.production ``` -When `NODE_ENV=production`, the Medusa application loads the environment variables from `.env.production`. Learn more about environment variables in [this guide](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md). +When `NODE_ENV=production`, the Medusa application loads the environment variables from `.env.production`. Learn more in the [environment variables guide](https://docs.medusajs.com/learn/fundamentals/environment-variables/index.html.md). 3. Set `NODE_ENV` to `production` in the system environment variable: @@ -76,9 +59,9 @@ npm run start ### Authentication Locally in Production Build -When the Medusa application is started in production (`NODE_ENV=production`) or staging modes, cookie settings are more strict. You can only use cookie authentication if the client application is served from the same domain as the Medusa server, and the domain is not `localhost` or part of the [public suffix list](https://publicsuffix.org/). +When the Medusa application is started in production (`NODE_ENV=production`) or staging mode, cookie settings are stricter. Cookie authentication only works if the client application is served from the same domain as the Medusa server, and the domain is not `localhost` or part of the [public suffix list](https://publicsuffix.org/). -So, if you try to access the Medusa Admin locally in production mode, you won't be able to log in. +So if you try to access the Medusa Admin locally in production mode, you won't be able to log in. To access the Medusa Admin locally in production mode, set the `projectConfig.cookieOptions` in your `medusa-config.ts` file to be less strict. For example: @@ -96,12 +79,61 @@ module.exports = defineConfig({ In this example, you set `sameSite` to `lax` and `secure` to `false`, which allows cookies to be sent over non-secure connections and from different domains. -Then, rebuild the Medusa application and start it again, as described in the [steps above](#start-built-medusa-application). You can now access the Medusa Admin locally in production mode. +Then rebuild the Medusa application and start it again as described in the [steps above](#start-built-medusa-application). You can now access the Medusa Admin locally in production mode. Make sure to remove the `projectConfig.cookieOptions` configuration once you're done testing locally, as it's not secure for production environments. *** +## Build Output + +The `build` command creates a `.medusa/server` directory in the root of your project that contains your build assets. Do not commit this directory to your repository. This directory should be generated as part of your deployment process. + +The `.medusa/server` directory contains the following: + +![.medusa/server directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1760709518/Medusa%20Book/output-dir_dlklk6.jpg) + +- `public/admin`: Contains the production build of the admin dashboard. The `public` directory is publicly accessible. +- `src`: Contains the compiled JavaScript files of your `src` directory. +- `instrumentation.js`: The compiled [instrumentation configuration file](https://docs.medusajs.com/learn/debugging-and-testing/instrumentation/index.html.md), if you have one. +- `medusa-config.js`: The compiled Medusa configuration file. +- `package.json` and a lock file: The dependencies required to run the Medusa application in production. + +### Built Assets + +The `build` command compiles and copies `.{ts,js,tsx,jsx}` files in your project, such as those in the root directory and in the `src` directory. + +If you have other assets, such as JSON files or fonts, that you need in your Medusa backend at runtime, you need to copy them to the `.medusa/server` directory as part of your build process. + +For example, consider you have a `src/data` directory that contains JSON files needed at runtime. You can add a `postbuild` script to your `package.json` file to copy this directory after the build process: + +```json title="package.json" +{ + "scripts": { + "postbuild": "cp -r src/data .medusa/server/src/data", + "build": "medusa build && npm run postbuild" + } +} +``` + +This script copies the `src/data` directory to the `.medusa/server` directory after the build process. + +Do not expose sensitive files in your deployments, especially in the `.medusa/server/public` directory, as they will be publicly accessible. Sensitive files include those containing API keys, database credentials, or any other confidential information. + +### Customize Admin Build + +The admin dashboard is built with [Vite](!https://vitejs.dev/). If you need to customize the build process to include additional static assets, you can modify the Vite configuration with the [admin.vite](https://docs.medusajs.com/learn/configurations/medusa-config/index.html.md) option in your `medusa-config.ts` file. + +### Separate Admin Build + +The `build` command accepts a `--admin-only` option that outputs the admin to the `.medusa/admin` directory. This is useful when deploying the admin dashboard separately, such as on Vercel: + +```bash +npx medusa build --admin-only +``` + +*** + ## Deploying Production Build The next chapter covers how to deploy the production build. diff --git a/www/apps/cloud/app/deployments/page.mdx b/www/apps/cloud/app/deployments/page.mdx index 33536a3b9d..2f45056159 100644 --- a/www/apps/cloud/app/deployments/page.mdx +++ b/www/apps/cloud/app/deployments/page.mdx @@ -17,7 +17,9 @@ A deployment is created from the latest source code of an [environment](../envir The latest deployment of an environment is the live version of that environment, unless you [redeploy a previous deployment](#redeploy-a-deployment). -### How are Deployments Created? +--- + +## How are Deployments Created? For long-lived environments, Medusa creates a new deployment every time you push a new commit to the environment's branch. For example, if your Production environment is connected to the `main` branch, Medusa will create a new Production deployment every time you push a new commit to the `main` branch. @@ -25,6 +27,50 @@ For short-lived preview environments, Medusa creates a new environment and deplo --- +## Build Process for Deployments + +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: + +```json title="package.json" +{ + "scripts": { + "build": "medusa build && npm run other-build-steps" + } +} +``` + + + +You can replace `npm run other-build-steps` with the appropriate command for your package manager, such as `yarn other-build-steps`. + + + +### What Gets Deployed? + +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. + + + +Learn more about the `.medusa/server` directory in the [Build guide](!docs!/learn/build#output-directory-structure). + + + +So, if you have custom assets like JSON files that your application needs at runtime, make sure to copy them to the `.medusa/server` directory after the `medusa build` command in your `build` script. + +For example, if your application needs a `src/data/custom.json` file at runtime, you can add a script that copies it to `.medusa/server/src/data/custom.json` after the build process is complete. + +You can also customize the Medusa Admin build configurations using the [admin.vite](!docs!/learn/configurations/medusa-config#adminvite) option in your `medusa-config.ts` file. + + + +Do not expose sensitive files in your deployments, especially in the `.medusa/server/public` directory, as they will be publicly accessible. Sensitive files include those containing secret API keys, database credentials, or any other confidential information. + + + +--- + ## Find Project Deployments You can find the deployments for a project in its dashboard. diff --git a/www/apps/cloud/app/deployments/troubleshooting/page.mdx b/www/apps/cloud/app/deployments/troubleshooting/page.mdx new file mode 100644 index 0000000000..f505b6cf4b --- /dev/null +++ b/www/apps/cloud/app/deployments/troubleshooting/page.mdx @@ -0,0 +1,46 @@ +export const metadata = { + title: `Troubleshooting Cloud Deployments`, +} + +# {metadata.title} + +In this guide, you'll find solutions to common issues that may arise when deploying your Medusa applications on Cloud. + +## Files Not Found After Deployment + +Before deploying your Medusa application on Cloud, Medusa runs the `build` script defined in your `package.json` file, then copies only the output of the [build process](!docs!/learn/build), which is the `.medusa/server` directory. + +The `.medusa/server` directory holds the compiled JavaScript files of your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production. + +If you have custom files needed at runtime, such as a `src/data` directory that holds JSON files, modify the `build` script in your `package.json` file to copy these files to the `.medusa/server` directory after the build process. + +For example: + +```json title="package.json" +{ + "scripts": { + "postbuild": "cp -r src/data .medusa/server/src/data", + "build": "medusa build && npm run postbuild" + } +} +``` + +This script copies the `src/data` directory to the `.medusa/server` directory following the build process. + +Learn more in the [Deployments Guide](../page.mdx#build-process-for-deployments). + + + +You can replace `npm run postbuild` with the appropriate command for your package manager, such as `yarn postbuild`. + + + +--- + +## Troubleshooting Other Cloud Deployment Issues + +To troubleshoot other Cloud deployment issues, you can: + +- [Check the build and runtime logs of your deployment](../../logs/page.mdx). +- [Refer to Medusa's troubleshooting guides](!resources!/troubleshooting). +- Contact support for help. \ No newline at end of file diff --git a/www/apps/cloud/app/projects/page.mdx b/www/apps/cloud/app/projects/page.mdx index 1577804ace..0776c044cf 100644 --- a/www/apps/cloud/app/projects/page.mdx +++ b/www/apps/cloud/app/projects/page.mdx @@ -131,10 +131,7 @@ Once the project is created and deployed, you'll receive a notification in the C ## Troubleshooting Project Creation -If you encounter any issues while creating a project: - -- [Check the build and runtime logs of the project's production deployment](../logs/page.mdx). -- Contact support for help. +If you encounter any issues while creating a project, [check common deployment issues and their solutions](../deployments/troubleshooting/page.mdx) --- diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs index dfe8933efe..df57256837 100644 --- a/www/apps/cloud/generated/edit-dates.mjs +++ b/www/apps/cloud/generated/edit-dates.mjs @@ -1,9 +1,9 @@ export const generatedEditDates = { "app/page.mdx": "2025-09-11T15:21:38.987Z", "app/organization/page.mdx": "2025-06-12T14:43:20.772Z", - "app/projects/page.mdx": "2025-10-02T11:49:21.541Z", + "app/projects/page.mdx": "2025-10-17T13:38:32.827Z", "app/environments/page.mdx": "2025-10-15T15:25:09.940Z", - "app/deployments/page.mdx": "2025-10-15T15:23:16.572Z", + "app/deployments/page.mdx": "2025-10-17T14:40:07.793Z", "app/organizations/page.mdx": "2025-10-02T11:31:07.315Z", "app/notifications/page.mdx": "2025-10-15T15:25:33.672Z", "app/database/page.mdx": "2025-10-15T15:20:06.292Z", @@ -23,5 +23,6 @@ export const generatedEditDates = { "app/pricing/page.mdx": "2025-09-05T10:31:59.059Z", "app/sign-up/page.mdx": "2025-10-08T14:40:47.993Z", "app/comparison/page.mdx": "2025-09-30T06:17:40.257Z", - "app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z" + "app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z", + "app/deployments/troubleshooting/page.mdx": "2025-10-17T14:44:22.894Z" } \ No newline at end of file diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs index 7ddbb71878..28cf21852c 100644 --- a/www/apps/cloud/generated/sidebar.mjs +++ b/www/apps/cloud/generated/sidebar.mjs @@ -106,7 +106,16 @@ export const generatedSidebars = [ "type": "link", "title": "Deployments", "path": "/deployments", - "children": [] + "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Troubleshooting", + "path": "/deployments/troubleshooting", + "children": [] + } + ] } ] }, diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs index 367a8290b5..8eb2ee5d87 100644 --- a/www/apps/cloud/sidebar.mjs +++ b/www/apps/cloud/sidebar.mjs @@ -72,6 +72,13 @@ export const sidebar = [ type: "link", title: "Deployments", path: "/deployments", + children: [ + { + type: "link", + title: "Troubleshooting", + path: "/deployments/troubleshooting", + }, + ], }, ], },