docs: add a note about installing preview version (#8648)

- Add a note about ensuring a package's version is set to `preview` in `package.json`
- Add a troubleshooting guide for deployments with a section about preview versions
- Added a troubleshooting section to the railway deployment guide about preview versions

Closes #8646
Closes DOCS-913

www/apps/resources/app/architectural-modules/cache/in-memory/page.mdx

@@ -28,6 +28,12 @@ To install the In-Memory Cache Module, run the following command in the director
 npm install @medusajs/cache-inmemory@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 ```js title="medusa-config.js"

www/apps/resources/app/architectural-modules/cache/redis/page.mdx

@@ -24,6 +24,12 @@ To install Redis Cache Module, run the following command in the directory of you
 npm install @medusajs/cache-redis@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 export const highlights = [

www/apps/resources/app/architectural-modules/event/local/page.mdx

@@ -26,6 +26,12 @@ To install Local Event Bus Module, run the following command in the directory of
 npm install @medusajs/event-bus-local@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 ```js title="medusa-config.js"

www/apps/resources/app/architectural-modules/event/redis/page.mdx

@@ -28,6 +28,12 @@ To install Redis Event Bus Module, run the following command in the directory of
 npm install @medusajs/event-bus-redis@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 export const highlights = [

www/apps/resources/app/architectural-modules/file/local/page.mdx

@@ -30,6 +30,12 @@ To install the Local File Module Provider, run the following command in the dire
 npm install @medusajs/file-local-next@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `providers` array of the File Module:
 
 <Note>

www/apps/resources/app/architectural-modules/file/s3/page.mdx

@@ -96,6 +96,12 @@ To install the S3 File Module Provider, run the following command in the directo
 npm install @medusajs/file-s3@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `providers` array of the File Module:
 
 <Note>

www/apps/resources/app/architectural-modules/notification/local/page.mdx

@@ -24,6 +24,12 @@ To install the Local Notification Module Provider, run the following command in
 npm install @medusajs/notification-local@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `providers` array of the Notification Module:
 
 <Note>

www/apps/resources/app/architectural-modules/notification/sendgrid/page.mdx

@@ -26,6 +26,12 @@ To install the SendGrid Notification Module Provider, run the following command
 npm install @medusajs/notification-sendgrid@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `providers` array of the Notification Module:
 
 <Note>

www/apps/resources/app/architectural-modules/workflow-engine/in-memory/page.mdx

@@ -28,6 +28,12 @@ To install the In-Memory Workflow Engine Module, run the following command in th
 npm install @medusajs/workflow-engine-inmemory@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 ```js title="medusa-config.js"

www/apps/resources/app/architectural-modules/workflow-engine/redis/page.mdx

@@ -24,6 +24,12 @@ To install Redis Workflow Engine Module, run the following command in the direct
 npm install @medusajs/workflow-engine-redis@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module into the `modules` property of the exported object in `medusa-config.js`:
 
 export const highlights = [

www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/page.mdx

@@ -36,6 +36,12 @@ To install the Stripe Module Provider, run the following command in the director
 npm install @medusajs/payment-stripe@preview
 ```
 
+<Note>
+
+Make sure that the version added in `package.json` is `preview` to avoid errors with installation and updates in the future.
+
+</Note>
+
 Next, add the module to the array of providers passed to the Payment Module:
 
 ```js title="medusa-config.js"

www/apps/resources/app/deployment/medusa-application/railway/page.mdx

@@ -2,6 +2,9 @@
 sidebar_label: "Railway"
 ---
 
+import { DetailsList } from "docs-ui"
+import OutdatedPreviewContent from "../../../troubleshooting/_sections/common-installation-errors/outdated-preview.mdx"
+
 export const metadata = {
   title: `Deploy Medusa Application to Railway`,
 }
@@ -413,3 +416,12 @@ To check issues or errors in your deployed Medusa application:
 1. Click on the card of the Medusa application in server mode.
 2. Click on the Deployments tab.
 3. Click on the View Logs button.
+
+<DetailsList
+  sections={[
+    {
+      title: "Dependencies Using Outdated Preview Version",
+      content: <OutdatedPreviewContent />
+    }
+  ]}
+/>

www/apps/resources/app/troubleshooting/_sections/common-installation-errors/outdated-preview.mdx

@@ -0,0 +1,10 @@
+If you've installed a preview version of a package, such as `@medusajs/file-s3`, make sure its version in `package.json` is set to `preview`:
+
+```json title="package.json"
+"dependencies": {
+  // ...
+  "@medusajs/file-s3": "preview"
+}
+```
+
+Otherwise, unexpected errors may occur when running the Medusa application due to outdated version installed.

www/apps/resources/app/troubleshooting/deployment/page.mdx

@@ -0,0 +1,11 @@
+import OutdatedPreviewContent from "../_sections/common-installation-errors/outdated-preview.mdx"
+
+export const metadata = {
+  title: `General Deployment Errors`,
+}
+
+# {metadata.title}
+
+## Dependencies Using Outdated Preview Version
+
+<OutdatedPreviewContent />

www/apps/resources/generated/edit-dates.mjs

@@ -131,7 +131,7 @@ export const generatedEditDates = {
   "app/contribution-guidelines/docs/page.mdx": "2024-05-13T18:55:11+03:00",
   "app/create-medusa-app/page.mdx": "2024-08-05T11:10:55+03:00",
   "app/deployment/admin/vercel/page.mdx": "2024-07-31T17:01:33+03:00",
-  "app/deployment/medusa-application/railway/page.mdx": "2024-07-31T17:01:33+03:00",
+  "app/deployment/medusa-application/railway/page.mdx": "2024-08-19T07:19:54.945Z",
   "app/deployment/storefront/vercel/page.mdx": "2024-07-26T07:21:31+00:00",
   "app/deployment/page.mdx": "2024-07-25T09:55:22+03:00",
   "app/integrations/page.mdx": "2024-07-19T08:49:08+00:00",
@@ -255,6 +255,7 @@ export const generatedEditDates = {
   "app/admin-widget-injection-zones/page.mdx": "2024-05-29T13:50:19+03:00",
   "app/architectural-modules/notification/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/architectural-modules/event/create/page.mdx": "2024-07-04T17:26:03+03:00",
+  "app/troubleshooting/deployment/page.mdx": "2024-08-19T07:19:40.924Z",
   "references/core_flows/Order/functions/core_flows.Order.orderEditUpdateItemQuantityValidationStep/page.mdx": "2024-08-20T00:10:58.913Z",
   "references/core_flows/Order/functions/core_flows.Order.orderEditUpdateItemQuantityWorkflow/page.mdx": "2024-08-20T00:10:58.949Z",
   "references/core_flows/Order/functions/core_flows.Order.updateOrderEditItemQuantityValidationStep/page.mdx": "2024-08-20T00:10:59.121Z",

www/apps/resources/generated/files-map.mjs

@@ -987,6 +987,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/database-errors/page.mdx",
     "pathname": "/troubleshooting/database-errors"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/deployment/page.mdx",
+    "pathname": "/troubleshooting/deployment"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/eaddrinuse/page.mdx",
     "pathname": "/troubleshooting/eaddrinuse"

www/apps/resources/generated/sidebar.mjs

@@ -8419,6 +8419,14 @@ export const generatedSidebar = [
                 "children": []
               }
             ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/troubleshooting/deployment",
+            "title": "Deployment",
+            "children": []
           }
         ]
       }

www/apps/resources/sidebar.mjs

@@ -2194,6 +2194,11 @@ export const sidebar = sidebarAttachHrefCommonOptions([
               },
             ],
           },
+          {
+            type: "link",
+            path: "/troubleshooting/deployment",
+            title: "Deployment",
+          },
         ],
       },
     ],