docs: added migration guide for Medusa React (#3066)

* docs: added migration guide for Medusa React * docs: fixed vale error
2023-01-19 16:59:49 +02:00
parent 296d6e229f
commit 7cafff14b9
22 changed files with 222 additions and 367 deletions
@@ -0,0 +1,9 @@
+{
+  "position": 3,
+  "collapsed": true,
+  "link": null,
+  "label": "Medusa Admin",
+  "customProps": {
+    "sort": "desc"
+  }
+}
@@ -1,5 +1,6 @@
 ---
 description: 'Actions Required for Vite Update'
+sidebar_label: 'Medusa Admin: Vite'
 ---

 # Updating Medusa Admin from Gatsby to Vite
@@ -4,7 +4,7 @@ hide_table_of_contents: true

 import DocCardList from '@theme/DocCardList';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
-import filterListItems from '@site/src/utils/filterListItems';
+import filterListItems, { flattenList } from '@site/src/utils/filterListItems';

 # Upgrade Guides

@@ -12,8 +12,12 @@ Find in this page the upgrade guides that require necessary steps when upgrading

 ## Server

-<DocCardList items={filterListItems(useCurrentSidebarCategory().items, /^(?!.*\/admin\/).*$/)}/>
+<DocCardList items={filterListItems(flattenList(useCurrentSidebarCategory().items), /\/medusa\-core\//)}/>
+
+## Medusa React
+
+<DocCardList items={filterListItems(flattenList(useCurrentSidebarCategory().items), /\/medusa-react\//)}/>

 ## Admin

-<DocCardList items={filterListItems(useCurrentSidebarCategory().items, /\/admin\//)}/>
+<DocCardList items={filterListItems(flattenList(useCurrentSidebarCategory().items), /\/admin\//)}/>
@@ -1,4 +1,5 @@
 ---
+sidebar_position: 7
 description: 'Actions Required for v.1.3.0'
 ---

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 6
 description: 'Actions Required for v.1.3.0'
 ---

@@ -8,7 +9,7 @@ Following the addition of feature flags in version v1.3.3 and the addition of th

 :::note

-In version 1.3.6, Sales Channels are available but guraded by [feature flags](../feature-flags/toggle.md). If you don’t have Sales Channels enabled, you don’t need to follow the steps detailed in this migration script.
+In version 1.3.6, Sales Channels are available but guraded by [feature flags](../../feature-flags/toggle.md). If you don’t have Sales Channels enabled, you don’t need to follow the steps detailed in this migration script.

 :::

@@ -30,7 +31,7 @@ These environment variables are used in the data migration scripts in this upgra

 ## Sales Channels

-Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../feature-flags/toggle.md). By enabling Sales Channels, developers and users can associate products and other entities with a specific Sales Channel.
+Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../../feature-flags/toggle.md). By enabling Sales Channels, developers and users can associate products and other entities with a specific Sales Channel.

 However, if you upgraded Medusa to v1.3.5 and enabled Sales Channels, you must add every product to at least one Sales Channel manually. Otherwise, products can’t be added to carts in different Sales Channels.

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 5
 description: 'Actions Required for v.1.3.0'
 ---

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 4
 description: 'Actions Required for v.1.6.1'
 ---

@@ -1,14 +1,15 @@
 ---
+sidebar_position: 3
 description: 'Actions Required for v.1.7.0'
 ---

 # v1.7.0

-Version `1.7.0` of Medusa introduces a breaking change in the [CustomerService](../../../references/services/classes/CustomerService.md).
+Version `1.7.0` of Medusa introduces a breaking change in the [CustomerService](../../../../references/services/classes/CustomerService.md).

 ## Overview

-In this new version, the method [`retrieveByEmail` in the Customer Service](../../../references/services/classes/CustomerService.md#retrievebyemail) has been deprecated in favor of other methods. Read the actions required below to learn which methods to use instead.
+In this new version, the method [`retrieveByEmail` in the Customer Service](../../../../references/services/classes/CustomerService.md#retrievebyemail) has been deprecated in favor of other methods. Read the actions required below to learn which methods to use instead.

 In addition, after introducing the Claim Order feature, this version of Medusa introduces changes in the database that allows two customers having the same email based on the value of the `has_account` field. This change requires running migrations after the update.

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 2
 description: 'Actions Required for v.1.7.1'
 ---

@@ -65,7 +66,7 @@ const myJob = async (container, options) => {
 export default myJob
 ```

-You can learn more in the [How to Create a Scheduled Job](../scheduled-jobs/create.md) documentation.
+You can learn more in the [How to Create a Scheduled Job](../../scheduled-jobs/create.md) documentation.

 ### Change to Payment Provider

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 1
 description: 'Actions Required for v.1.7.3'
 ---

@@ -8,7 +9,7 @@ Version 1.7.3 of Medusa changes the feature flag value for Sales Channels and Pu

 ## Overview

-Sales Channels and Publishable API Keys were introduced in previous versions of Medusa, but guarded by [feature flags](../feature-flags/toggle.md) This meant that developers had to manually enable them to use them.
+Sales Channels and Publishable API Keys were introduced in previous versions of Medusa, but guarded by [feature flags](../../feature-flags/toggle.md) This meant that developers had to manually enable them to use them.

 Version 1.7.3 of Medusa keeps the feature flags for these two features, but they’re now enabled by default. This requires running the necessary migrations to ensure your server works as expected.

@@ -50,4 +51,4 @@ node ./node_modules/@medusajs/medusa/dist/scripts/sales-channels-migration.js

 ## Disabling Feature Flags

-Although this version enables Sales Channels and Publishable API Keys by default, you can still turn them off using feature flags. Learn more in [this documentation](../feature-flags/toggle.md#disable-feature-flags)
+Although this version enables Sales Channels and Publishable API Keys by default, you can still turn them off using feature flags. Learn more in [this documentation](../../feature-flags/toggle.md#disable-feature-flags)
@@ -0,0 +1,9 @@
+{
+  "position": 1,
+  "collapsed": false,
+  "link": null,
+  "label": "Server",
+  "customProps": {
+    "sort": "desc"
+  }
+}
@@ -0,0 +1,58 @@
+---
+description: 'Actions Required for v4.0.2'
+---
+
+<!-- vale docs.HeadingColons = NO -->
+
+# Medusa React: v4.0.2
+
+<!-- vale docs.HeadingColons = YES -->
+
+Version 4.0.2 of Medusa React introduces a new update in its dependencies which can lead to breaking changes.
+
+## Overview
+
+Medusa React previously required installing React Query v3 as a peer dependency. This version changes the peer dependency requirement to [Tanstack Query](https://tanstack.com/query/latest/docs/react/overview) - the updated version of React Query.
+
+This requires additional actions related to installing the new dependency and changing imports.
+
+---
+
+## Actions Required
+
+### Update Medusa Dependencies
+
+To update to the latest version of Medusa React, run the following command in your custom storefront or admin to update both Medusa React and the core package:
+
+```bash
+npm update medusa-react @medusajs/medusa
+```
+
+### Uninstall React Query v3
+
+As React Query v3 is not required as a peer dependency anymore, uninstall it from your custom storefront or admin:
+
+```bash npm2yarn
+npm remove react-query
+```
+
+### Install Tanstack Query
+
+Run the following command to install Tanstack Query:
+
+```bash npm2yarn
+npm install @tanstack/react-query
+```
+
+### Update Imports
+
+Across your custom storefront or admin project, change all imports from `react-query` to `@tanstack/react-query`.
+
+For example, update the import for `QueryClient` where you use it with Medusa Provider:
+
+```ts
+import { QueryClient } from "@tanstack/react-query"
+
+// this remains the same
+const queryClient = new QueryClient()
+```
@@ -0,0 +1,9 @@
+{
+  "position": 2,
+  "collapsed": true,
+  "link": null,
+  "label": "Medusa React",
+  "customProps": {
+    "sort": "desc"
+  }
+}
@@ -7,7 +7,7 @@ In this document, you’ll learn how to implement the claim order flow in a stor

 :::note

-This flow was added starting from Medusa v1.7. You can learn more about upgrading in the [upgrade guide](../backend/upgrade-guides/1-7-0.md).
+This flow was added starting from Medusa v1.7. You can learn more about upgrading in the [upgrade guide](../backend/upgrade-guides/medusa-core/1-7-0.md).

 :::