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
2024-08-22 11:33:24 +03:00
parent bb4c58d526
commit 810debc7bb
18 changed files with 118 additions and 1 deletions
@@ -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"
@@ -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 = [
@@ -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"
@@ -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 = [
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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"
@@ -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 = [
@@ -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"
@@ -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 />
+    }
+  ]}
+/>
@@ -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.
@@ -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 />
@@ -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",
@@ -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"
@@ -8419,6 +8419,14 @@ export const generatedSidebar = [
                "children": []
              }
            ]
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/troubleshooting/deployment",
+            "title": "Deployment",
+            "children": []
          }
        ]
      }
@@ -2194,6 +2194,11 @@ export const sidebar = sidebarAttachHrefCommonOptions([
              },
            ],
          },
+          {
+            type: "link",
+            path: "/troubleshooting/deployment",
+            title: "Deployment",
+          },
        ],
      },
    ],