docs: document build output + Cloud troubleshooting (#13774)

2025-10-20 15:45:11 +03:00
parent 1b6e53f032
commit d97a60d3c1
9 changed files with 232 additions and 58 deletions
@@ -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).
+
+<Note>
+
+You can replace `npm run postbuild` with the appropriate command for your package manager, such as `yarn postbuild`.
+
+</Note>
+
+---
+
+## 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.