docs: publish restructure (#3496)

* docs: added features and guides overview page * added image * added version 2 * added version 3 * added version 4 * docs: implemented new color scheme * docs: redesigned sidebar (#3193) * docs: redesigned navbar for restructure (#3199) * docs: redesigned footer (#3209) * docs: redesigned cards (#3230) * docs: redesigned admonitions (#3231) * docs: redesign announcement bar (#3236) * docs: redesigned large cards (#3239) * docs: redesigned code blocks (#3253) * docs: redesigned search modal and page (#3264) * docs: redesigned doc footer (#3268) * docs: added new sidebars + refactored css and assets (#3279) * docs: redesigned api reference sidebar * docs: refactored css * docs: added code tabs transition * docs: added new sidebars * removed unused assets * remove unusued assets * Fix deploy errors * fix incorrect link * docs: fixed code responsivity + missing icons (#3283) * docs: changed icons (#3296) * docs: design fixes to the sidebar (#3297) * redesign fixes * docs: small design fixes * docs: several design fixes after restructure (#3299) * docs: bordered icon fixes * docs: desgin fixes * fixes to code blocks and sidebar scroll * design adjustments * docs: restructured homepage (#3305) * docs: restructured homepage * design fixes * fixed core concepts icon * docs: added core concepts page (#3318) * docs: restructured homepage * design fixes * docs: added core concepts page * changed text of different components * docs: added architecture link * added missing prop for user guide * docs: added regions overview page (#3327) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page (#3331) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page * fix link * resolve link issues * docs: updated regions architecture image * docs: second-iteration fixes (#3347) * docs: redesigned document * design fixes * docs: added products overview page (#3354) * docs: added carts overview page (#3363) * docs: added orders overview (#3364) * docs: added orders overview * added links in overview * docs: added vercel redirects * docs: added soon badge for cards (#3389) * docs: resolved feedback changes + organized troubleshooting pages (#3409) * docs: resolved feedback changes * added extra line * docs: changed icons for restructure (#3421) * docs: added taxes overview page (#3422) * docs: added taxes overview page * docs: fix sidebar label * added link to taxes overview page * fixed link * docs: fixed sidebar scroll (#3429) * docs: added discounts overview (#3432) * docs: added discounts overview * fixed links * docs: added gift cards overview (#3433) * docs: added price lists overview page (#3440) * docs: added price lists overview page * fixed links * docs: added sales channels overview page (#3441) * docs: added sales overview page * fixed links * docs: added users overview (#3443) * docs: fixed sidebar border height (#3444) * docs: fixed sidebar border height * fixed svg markup * docs: added possible solutions to feedback component (#3449) * docs: added several overview pages + restructured files (#3463) * docs: added several overview pages * fixed links * docs: added feature flags + PAK overview pages (#3464) * docs: added feature flags + PAK overview pages * fixed links * fix link * fix link * fixed links colors * docs: added strategies overview page (#3468) * docs: automated upgrade guide (#3470) * docs: automated upgrade guide * fixed vercel redirect * docs: restructured files in docs codebase (#3475) * docs: restructured files * docs: fixed eslint exception * docs: finished restructure loose-ends (#3493) * fixed uses of backend * docs: finished loose ends * eslint fixes * fixed links * merged master * added update instructions for v1.7.12
2023-03-16 17:03:10 +02:00
parent f312ce1e0f
commit 1decaa27c7
415 changed files with 12422 additions and 5098 deletions
@@ -0,0 +1,6 @@
+{
+  "position": 3,
+  "collapsed": true,
+  "link": null,
+  "label": "Medusa Admin"
+}
@@ -0,0 +1,66 @@
+---
+description: 'Actions Required for Vite Update'
+sidebar_label: 'Medusa Admin: Vite'
+sidebar_custom_props:
+  iconName: 'computer-desktop-solid'
+---
+
+# Updating Medusa Admin from Gatsby to Vite
+
+Medusa Admin has been updated to Vite. Learn about breaking changes since the update.
+
+## Overview
+
+Medusa Admin previously was built using Gatsby. As of a recent update, the Admin is now migrated to Vite 3.
+
+This introduced breaking changes related to environment variables used and the published directory. Read below for actions required following this update.
+
+---
+
+## Required Node.js Version
+
+<!-- vale docs.Numbers = NO -->
+
+Following the change to Vite 3, the required Node.js version for the Admin has changed. [Vite 3](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) requires versions 14.8+ or 16+ of Node.js.
+
+<!-- vale docs.Numbers = YES -->
+
+---
+
+## Changed Environment Variables
+
+Previously, the Medusa Admin used the environment variables `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` to store the Medusa backend’s URL.
+
+After the update to Vite, the environment variable name changed to `MEDUSA_BACKEND_URL`.
+
+The Medusa admin remains backward compatible, which means you can still use the same environment variables. However, it is advised to make the change to the new variable.
+
+### Actions Required
+
+Change your `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` environment variables to be `MEDUSA_BACKEND_URL`:
+
+```bash
+MEDUSA_BACKEND_URL=<YOUR_BACKEND_URL>
+```
+
+---
+
+## Changed Publish Directory
+
+Previously, the build output of the Medusa Admin was placed in the `dist` directory. After this update, the build output is placed in the `public` directory.
+
+For local usage and development, this shouldn’t have an effect. However, this is a breaking change if you deployed Medusa admin.
+
+### Actions Required
+
+If you deployed your Medusa admin, you must change the Publish directory in your hosting.
+
+For Netlify, you can do that by following these steps:
+
+1. On your Medusa admin dashboard, click on “Site settings”.
+2. From the sidebar, choose “Build & deploy”.
+3. Find the “Build settings” section and click on the “Edit settings” button.
+4. Change the “Publish directory” field to `public`.
+5. Click on the Save button.
+
+This should trigger a new deployment of your Medusa admin. If not, you must redeploy it manually for changes to take effect.
@@ -0,0 +1,29 @@
+---
+hide_table_of_contents: true
+description: 'Upgrade guides on how to update the Medusa backend along with other Medusa components to the latest version.'
+---
+
+import DocCard from '@theme/DocCard';
+import getFirstCategoryItem from '@site/src/utils/getFirstCategoryItem';
+
+# Upgrade Guides
+
+Find in this page the upgrade guides that require necessary steps when upgrading to a new version.
+
+## Backend
+
+<DocCard
+  item={getFirstCategoryItem('Backend')}
+/>
+
+## Medusa React
+
+<DocCard
+  item={getFirstCategoryItem('Medusa React')}
+/>
+
+## Admin
+
+<DocCard
+  item={getFirstCategoryItem('Medusa Admin')}
+/>
@@ -0,0 +1,100 @@
+---
+description: 'Actions Required for v.1.3.0'
+---
+
+# v1.3.0
+
+Version 1.3.0 of Medusa introduces new features including the addition of Line Item Adjustments and a more advanced Promotions API, as well as a change in loading environment variables into your Medusa backend. The changes do not affect the public APIs and require only running necessary data migrations.
+
+## Prerequisites
+
+Both the actions required for this update need you to set the following environment variables:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_LOGGING=true
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `<DATABASE_URL>` with your PostgreSQL database URL.
+
+---
+
+## Environment Variables
+
+In previous versions of Medusa, The backend automatically loads all environment variables in the `.env` file at the root of the Medusa backend.
+
+This new update removes loading it automatically and gives developers the freedom in how to load their environment variables. All environment variables will be loaded by default from the system’s environment variables.
+
+### Actions Required
+
+If you use a `.env` file to load environment variables on your backend, you need to load the variables manually in `medusa-config.js`.
+
+You can add the following code snippet at the top of the file which uses the [dotenv](https://www.npmjs.com/package/dotenv) package to load the environment variables based on the current Node environment:
+
+```jsx
+const dotenv = require("dotenv")
+
+ let ENV_FILE_NAME = ""
+ switch (process.env.NODE_ENV) {
+  case "production":
+    ENV_FILE_NAME = ".env.production"
+    break
+  case "staging":
+    ENV_FILE_NAME = ".env.staging"
+    break
+  case "test":
+    ENV_FILE_NAME = ".env.test"
+    break
+  case "development":
+  default:
+    ENV_FILE_NAME = ".env"
+    break
+ }
+
+ try {
+  dotenv.config({ path: process.cwd() + "/" + ENV_FILE_NAME })
+ } catch (e) {
+  // handle error
+ }
+```
+
+---
+
+## Line Item Adjustments
+
+This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities.
+
+It introduces a new entity `LineItemAdjustment` which gives more flexibility to adjust the pricing of line items in a cart, order, or swap. A discount can be added, removed, or modified and the price will reflect on the total calculation of the cart, order, or swap.
+
+This also introduces an optimization to the calculation of totals, as it is no longer necessary to calculate the discounts every time the totals are retrieved.
+
+### Actions Required
+
+This new version adds a new data migration script that will go through your list of existing orders and add line item adjustments for each of the line items in the order.
+
+For that reason, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/line-item-adjustment-migration.js
+```
+
+---
+
+## Advanced Discount Conditions
+
+This new version of Medusa holds advanced promotions functionalities to provide store operators with even more customization capabilities when creating discounts. You can now add even more conditions to your discounts to make them specific for a set of products, collections, customer groups, and more.
+
+This change required creating a new entity `DiscountCondition` which belongs to `DiscountRule` and includes a few relationships with other entities to make the aforementioned feature possible.
+
+### Actions Required
+
+To ensure your old discount rules play well with the new Promotions API and schema, this version includes a migration script that will go through your existing discount rules, create discount conditions for these rules, and move the former direct relationship between discount rules and products to become between discount conditions and products.
+
+For that reason, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/discount-rule-migration.js
+```
@@ -0,0 +1,45 @@
+---
+description: 'Actions Required for v.1.3.0'
+---
+
+# v1.3.6
+
+Following the addition of feature flags in version v1.3.3 and the addition of the Sales Channels API in v1.3.5, v1.3.6 introduces a data migration script that moves all products into the Default Sales Channel.
+
+:::note
+
+In version 1.3.6, Sales Channels are available but guraded by [feature flags](../../development/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.
+
+:::
+
+## Prerequisites
+
+Before performing the actions mentioned in this guide, you must set the following environment variables:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_LOGGING=true
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `<DATABASE_URL>` with your PostgreSQL database URL.
+
+---
+
+## Sales Channels
+
+Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../../development/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.
+
+v1.3.6 introduces a data migration script that automates this process for you by moving all your products into a default Sales Channel. This ensures that you can use the Sales Channels feature without it affecting the user experience in your store.
+
+### Actions Required
+
+If you’ve enabled Sales Channels, it’s essential to run the data migration script after upgrading your backend and before starting your Medusa backend:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/sales-channels-migration.js
+```
@@ -0,0 +1,39 @@
+---
+description: 'Actions Required for v.1.3.8'
+---
+
+# v1.3.8
+
+Updating your medusa backend to version `1.3.8` may cause issues when using NPM. Please refer to this guide for more details on how to resolve it.
+
+## Update Using Yarn
+
+It's highly recommended to use [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update.
+
+---
+
+## Resolving Update Issues with NPM
+
+### Update All Medusa Dependencies
+
+If you face any errors during your update to version `1.3.8`, make sure to update all Medusa dependencies you’re using on your backend. This includes `medusa-interfaces`, `@medusajs/medusa-cli`, or any of Medusa’s official plugins.
+
+You can update to the latest version of these using the `@latest` version tag. For example:
+
+```bash
+npm install medusa-interfaces@latest
+```
+
+### Use Legacy Peer Dependencies Option
+
+:::caution
+
+This solution can be used as a workaround and should be used with caution to avoid any issues while using Medusa.
+
+:::
+
+If all fails, you can use the `--legacy-peer-deps` option while updating Medusa:
+
+```bash
+npm install @medusajs/medusa@latest --legacy-peer-deps
+```
@@ -0,0 +1,23 @@
+---
+description: 'Actions Required for v.1.6.1'
+---
+
+# v1.6.1
+
+Updating your medusa backend to version `1.6.1` requires running migrations on your backend.
+
+## Overview
+
+As the new version `1.6.1` make changes to the database schema, it is required to run new migrations before you start your backend.
+
+Without running the migrations, you might have trouble accessing and using the Medusa admin.
+
+---
+
+## Actions Required
+
+After updating your backend, run migrations with the following command:
+
+```bash
+medusa migrations run
+```
@@ -0,0 +1,49 @@
+---
+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).
+
+## 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 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.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+Run the following command to run migrations:
+
+```bash
+medusa migrations run
+```
+
+### Change Used Methods
+
+Instead of using `customerService.retrieveByEmail`, you should now use the methods `customerService.retrieveRegisteredByEmail` or `customerService.retrieveUnregisteredByEmail`.
+
+The `customerService.retrieveRegisteredByEmail` method allows you to retrieve a registered customer by email:
+
+```ts
+customerService.retrieveRegisteredByEmail("example@gmail.com")
+```
+
+On the other hand, the `retrieveUnregisteredByEmail` method allows to retrieve guest customers by email:
+
+```jsx
+customerService.retrieveUnregisteredByEmail("example@gmail.com")
+```
+
+To retrieve a customer by email regardless of whether they are registered or not, you can use the `customerService.list` method instead:
+
+```ts
+customerService.list({
+  email: "example@gmail.com",
+})
+```
@@ -0,0 +1,137 @@
+---
+description: 'Actions Required for v.1.7.1'
+---
+
+# v1.7.1
+
+Version `1.7.1` of Medusa introduces the `JobSchedulerService` which changes how scheduled/cron jobs are created.
+
+## Overview
+
+Version `1.7.1` of Medusa introduces a new service `JobSchedulerService` that handles all logic and functionality related to created scheduled (previously named cron jobs).
+
+With this introduction, the previous use of `EventBus` to create a cron job has been deprecated of using the `JobSchedulerService`.
+
+In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+In the directory of your Medusa backend, run the following command after updating the backend:
+
+```bash
+medusa migrations run
+```
+
+### Run Migration Script
+
+Following the fix gift cards calculation, you also need to run a migration script after updating the backend.
+
+Start by adding the following environment variables in `.env`:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_USERNAME=<DATABASE_USERNAME>
+TYPEORM_PASSWORD=<DATABASE_PASSWORD>
+TYPEORM_DATABASE=<DATABASE_DATABASE>
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+Make sure to replace `<DATABASE_URL>`, `<DATABASE_USERNAME>`, `<DATABASE_PASSWORD>`, and `<DATABASE_DATABASE>` with your database connection details.
+
+Then, run the following command in the root directory of your Medusa backend:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/gift-card-tax-rate-migration.js
+```
+
+### Change to JobSchedulerService
+
+In your loader file that creates a cron job, replace the use of `eventBus` to `jobSchedulerService`:
+
+```ts
+const myJob = async (container, options) => {
+  const jobSchedulerService = container.resolve(
+    "jobSchedulerService"
+  )
+  jobSchedulerService.create(
+    "my-job",
+    {},
+    "0 0 * * *",
+    async () => {
+      // ...
+    }
+  )
+}
+
+export default myJob
+```
+
+You can learn more in the [How to Create a Scheduled Job](../../development/scheduled-jobs/create.md) documentation.
+
+### Change to Payment Provider
+
+This version of Medusa introduces a change in how payment providers are implemented. Mainly, the signature of the `createPayment` and `updatePayment` methods have changed, and the old signature is now deprecated.
+
+Although this change is currently backwards compatible, it is recommended to change the signature of these methods to the following:
+
+<!-- eslint-disable max-len -->
+
+```ts
+import { Cart, PaymentSessionData, PaymentContext, PaymentSessionResponse } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService<TransactionBaseService> {
+  // ...
+  async createPayment(
+    context: Cart & PaymentContext
+  ): Promise<PaymentSessionResponse> {
+    // ...
+  }
+
+  async updatePayment(
+    paymentSessionData: PaymentSessionData,
+    context: Cart & PaymentContext
+  ): Promise<PaymentSessionResponse> {
+    // ...
+  }
+}
+```
+
+Where `context` in both `createPayment` and `updatePayment` is made up of the following properties:
+
+```ts
+type PaymentContext = {
+  cart: {
+    context: Record<string, unknown>
+    id: string
+    email: string
+    shipping_address: Address | null
+    shipping_methods: ShippingMethod[]
+  }
+  currency_code: string
+  amount: number
+  resource_id?: string
+  customer?: Customer
+}
+```
+
+So, you can pass the previous `cart` parameter inside the new `context` paramter.
+
+Furthermore, these methods are now expected to return `PaymentSessionResponse`. It is made up of the following properties:
+
+```ts
+type PaymentSessionResponse = {
+  update_requests: { 
+    customer_metadata: Record<string, unknown>
+  }
+  session_data: Record<string, unknown>
+}
+```
+
+Where `session_data` would include the previously returned data from these methods. The property `update_requests` allows you to pass data from the payment provider plugin to the core to update internal resources. Currently, it can only be used to update the `metadata` field of the customer entity.
@@ -0,0 +1,37 @@
+---
+description: 'Actions Required for v.1.7.12'
+sidebar_custom_props:
+  iconName: 'server-stack-solid'
+---
+
+# v1.7.12
+
+Version 1.7.12 of Medusa introduces some database schema changes which require running the migrations command.
+
+## Overview
+
+This release contains a migration to ensure that the `product_variant_inventory` table is in its correct state. This is due to a mistake in a previous version where a column name was renamed in an already released migration. This could lead to errors if the migration was applied before the renaming of the column.
+
+---
+
+## How to Update
+
+Run the following command in the root directory of your Medusa Backend:
+
+```bash npm2yarn
+npm install @medusajs/medusa@latest @medusajs/medusa-cli@latest medusa-interfaces@latest
+```
+
+It's also recommended to update any other Medusa plugins or packages you have installed.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+After updating your Medusa server and before running it, run the following command to run the latest migrations:
+
+```bash
+medusa migrations run
+```
@@ -0,0 +1,53 @@
+---
+description: 'Actions Required for v.1.7.3'
+---
+
+# v1.7.3
+
+Version 1.7.3 of Medusa changes the feature flag value for Sales Channels and Publishable API Keys.
+
+## Overview
+
+Sales Channels and Publishable API Keys were introduced in previous versions of Medusa, but guarded by [feature flags](../../development/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 backend works as expected.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+After updating your Medusa backend and before running it, run the following command to run the latest migration:
+
+```bash
+medusa migrations run
+```
+
+### Run Migration Script for Sales Channels
+
+With the introduction of Sales Channels, products are now associated with them. To avoid inconsistencies with how products are linked to Sales Channels, it’s strongly recommended to run a migration script right after running the Medusa backend the first time.
+
+Start by adding the following environment variables:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_LOGGING=true
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+Make sure to replace `<DATABASE_URL>` with the connection URL of your database.
+
+Then, run the following command in the root of your Medusa backend:
+
+```bash
+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](../../development/feature-flags/toggle.md#disable-feature-flags)
@@ -0,0 +1,39 @@
+---
+description: 'Actions Required for v.1.7.6'
+sidebar_custom_props:
+  iconName: 'server-stack-solid'
+---
+
+# v1.7.6
+
+Version 1.7.6 of Medusa introduces some database schema changes which require running the migrations command.
+
+## Overview
+
+The latest versions of Medusa introduce the first implementations of Product Categories. The API layer of this feature is guarded by a [feature flag](../../development/feature-flags/toggle.md), but the changes to the database schema are not.
+
+This release introduces another migration for Product Categories. So, it is required to run migrations to ensure your backend works as expected.
+
+---
+
+## How to Update
+
+Run the following command in the root directory of your Medusa Backend:
+
+```bash npm2yarn
+npm install @medusajs/medusa@latest @medusajs/medusa-cli@latest medusa-interfaces@latest
+```
+
+It's also recommended to update any other Medusa plugins or packages you have installed.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+After updating your Medusa backend and before running it, run the following command to run the latest migrations:
+
+```bash
+medusa migrations run
+```
@@ -0,0 +1,6 @@
+{
+  "position": 1,
+  "collapsed": false,
+  "link": null,
+  "label": "Backend"
+}
@@ -0,0 +1,92 @@
+---
+description: 'Actions Required for v4.0.2'
+sidebar_custom_props:
+  iconName: 'react'
+---
+
+# Medusa React: v4.0.2
+
+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 npm2yarn
+npm install medusa-react@latest @medusajs/medusa@latest
+```
+
+### 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 uninstall 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()
+```
+
+### Fix No QueryClient set Errors
+
+If you're using a Next.js storefront, you might face the following error after this update when you run your storefront:
+
+```bash
+No QueryClient set
+```
+
+This is due to an issue related to Tanstack Query shipping `esm` modules in its latest versions and how Next.js uses Webpack.
+
+Although in future versions of `medusa-react` this issue will be fixed, you can add the following into `next.config.js` to fix this error:
+
+```js
+const path = require("path")
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // ... other configs
+  webpack: (config, options) => {
+    if (options.isServer) {
+      config.externals = [
+        "@tanstack/react-query", 
+        ...config.externals,
+      ]
+    }
+    const reactQuery = path.resolve(
+      require.resolve("@tanstack/react-query")
+    )
+    config.resolve.alias["@tanstack/react-query"] = reactQuery
+    return config
+  },
+}
+
+module.exports = nextConfig
+```
@@ -0,0 +1,6 @@
+{
+  "position": 2,
+  "collapsed": true,
+  "link": null,
+  "label": "Medusa React"
+}