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 08:33:24 +00: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 />