From 7cafff14b9c70b20b0104a70de915e736246d240 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 19 Jan 2023 16:59:49 +0200 Subject: [PATCH] docs: added migration guide for Medusa React (#3066) * docs: added migration guide for Medusa React * docs: fixed vale error --- .../upgrade-guides/admin/_category_.json | 9 + .../upgrade-guides/admin/admin-vite.md | 1 + .../advanced/backend/upgrade-guides/index.mdx | 10 +- .../upgrade-guides/{ => medusa-core}/1-3-0.md | 1 + .../upgrade-guides/{ => medusa-core}/1-3-6.md | 5 +- .../upgrade-guides/{ => medusa-core}/1-3-8.md | 1 + .../upgrade-guides/{ => medusa-core}/1-6-1.md | 1 + .../upgrade-guides/{ => medusa-core}/1-7-0.md | 5 +- .../upgrade-guides/{ => medusa-core}/1-7-1.md | 3 +- .../upgrade-guides/{ => medusa-core}/1-7-3.md | 5 +- .../medusa-core/_category_.json | 9 + .../upgrade-guides/medusa-react/4-0-2.md | 58 ++++ .../medusa-react/_category_.json | 9 + .../storefront/implement-claim-order.mdx | 2 +- docs/content/medusa-react/overview.md | 35 +- docs/content/usage/configurations.md | 2 +- packages/medusa-react/README.md | 303 +----------------- www/docs/docusaurus.config.js | 7 +- www/docs/netlify.toml | 30 +- www/docs/sidebars.js | 60 ++-- www/docs/src/utils/filterListItems.ts | 23 +- www/docs/src/utils/reverseSidebar.js | 10 + 22 files changed, 222 insertions(+), 367 deletions(-) create mode 100644 docs/content/advanced/backend/upgrade-guides/admin/_category_.json rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-3-0.md (99%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-3-6.md (83%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-3-8.md (98%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-6-1.md (96%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-7-0.md (81%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-7-1.md (96%) rename docs/content/advanced/backend/upgrade-guides/{ => medusa-core}/1-7-3.md (85%) create mode 100644 docs/content/advanced/backend/upgrade-guides/medusa-core/_category_.json create mode 100644 docs/content/advanced/backend/upgrade-guides/medusa-react/4-0-2.md create mode 100644 docs/content/advanced/backend/upgrade-guides/medusa-react/_category_.json create mode 100644 www/docs/src/utils/reverseSidebar.js diff --git a/docs/content/advanced/backend/upgrade-guides/admin/_category_.json b/docs/content/advanced/backend/upgrade-guides/admin/_category_.json new file mode 100644 index 0000000000..62f8fbd27e --- /dev/null +++ b/docs/content/advanced/backend/upgrade-guides/admin/_category_.json @@ -0,0 +1,9 @@ +{ + "position": 3, + "collapsed": true, + "link": null, + "label": "Medusa Admin", + "customProps": { + "sort": "desc" + } +} \ No newline at end of file diff --git a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md index 07b20e27f0..ccd133ec5a 100644 --- a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md +++ b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md @@ -1,5 +1,6 @@ --- description: 'Actions Required for Vite Update' +sidebar_label: 'Medusa Admin: Vite' --- # Updating Medusa Admin from Gatsby to Vite diff --git a/docs/content/advanced/backend/upgrade-guides/index.mdx b/docs/content/advanced/backend/upgrade-guides/index.mdx index 338ef22178..8f74590bc2 100644 --- a/docs/content/advanced/backend/upgrade-guides/index.mdx +++ b/docs/content/advanced/backend/upgrade-guides/index.mdx @@ -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 - + + +## Medusa React + + ## Admin - \ No newline at end of file + \ No newline at end of file diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-0.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-0.md similarity index 99% rename from docs/content/advanced/backend/upgrade-guides/1-3-0.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-0.md index 62768e48e8..36cbe8ca33 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-0.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-0.md @@ -1,4 +1,5 @@ --- +sidebar_position: 7 description: 'Actions Required for v.1.3.0' --- diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-6.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-6.md similarity index 83% rename from docs/content/advanced/backend/upgrade-guides/1-3-6.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-6.md index 7f021aef8a..7091e1e1f9 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-6.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-6.md @@ -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. diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-8.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-8.md similarity index 98% rename from docs/content/advanced/backend/upgrade-guides/1-3-8.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-8.md index 15fd523957..93d5cc925e 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-8.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-3-8.md @@ -1,4 +1,5 @@ --- +sidebar_position: 5 description: 'Actions Required for v.1.3.0' --- diff --git a/docs/content/advanced/backend/upgrade-guides/1-6-1.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-6-1.md similarity index 96% rename from docs/content/advanced/backend/upgrade-guides/1-6-1.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-6-1.md index 8c6d2a7365..a1a877fe78 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-6-1.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-6-1.md @@ -1,4 +1,5 @@ --- +sidebar_position: 4 description: 'Actions Required for v.1.6.1' --- diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-0.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-0.md similarity index 81% rename from docs/content/advanced/backend/upgrade-guides/1-7-0.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-0.md index d6ef8caa9d..91a1751003 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-0.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-0.md @@ -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. diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-1.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-1.md similarity index 96% rename from docs/content/advanced/backend/upgrade-guides/1-7-1.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-1.md index 3ac0f87a97..cd122587d1 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-1.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-1.md @@ -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 diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-3.md b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-3.md similarity index 85% rename from docs/content/advanced/backend/upgrade-guides/1-7-3.md rename to docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-3.md index 634c0de460..7f3144eea4 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-3.md +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/1-7-3.md @@ -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) diff --git a/docs/content/advanced/backend/upgrade-guides/medusa-core/_category_.json b/docs/content/advanced/backend/upgrade-guides/medusa-core/_category_.json new file mode 100644 index 0000000000..e2430d912e --- /dev/null +++ b/docs/content/advanced/backend/upgrade-guides/medusa-core/_category_.json @@ -0,0 +1,9 @@ +{ + "position": 1, + "collapsed": false, + "link": null, + "label": "Server", + "customProps": { + "sort": "desc" + } +} \ No newline at end of file diff --git a/docs/content/advanced/backend/upgrade-guides/medusa-react/4-0-2.md b/docs/content/advanced/backend/upgrade-guides/medusa-react/4-0-2.md new file mode 100644 index 0000000000..e388402a44 --- /dev/null +++ b/docs/content/advanced/backend/upgrade-guides/medusa-react/4-0-2.md @@ -0,0 +1,58 @@ +--- +description: 'Actions Required for v4.0.2' +--- + + + +# 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 +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() +``` diff --git a/docs/content/advanced/backend/upgrade-guides/medusa-react/_category_.json b/docs/content/advanced/backend/upgrade-guides/medusa-react/_category_.json new file mode 100644 index 0000000000..5ef0b7dd9a --- /dev/null +++ b/docs/content/advanced/backend/upgrade-guides/medusa-react/_category_.json @@ -0,0 +1,9 @@ +{ + "position": 2, + "collapsed": true, + "link": null, + "label": "Medusa React", + "customProps": { + "sort": "desc" + } +} \ No newline at end of file diff --git a/docs/content/advanced/storefront/implement-claim-order.mdx b/docs/content/advanced/storefront/implement-claim-order.mdx index ea62a6dd7c..0d964128d5 100644 --- a/docs/content/advanced/storefront/implement-claim-order.mdx +++ b/docs/content/advanced/storefront/implement-claim-order.mdx @@ -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). ::: diff --git a/docs/content/medusa-react/overview.md b/docs/content/medusa-react/overview.md index cc73ac52e9..b4863eb5a1 100644 --- a/docs/content/medusa-react/overview.md +++ b/docs/content/medusa-react/overview.md @@ -13,13 +13,20 @@ Alternatively, you can use Medusa’s [JS Client](../js-client/overview.md) or t In the directory holding your React-based storefront or admin dashboard, run the following command to install Medusa React: ```bash npm2yarn -npm install medusa-react react-query @medusajs/medusa +npm install medusa-react @tanstack/react-query @medusajs/medusa ``` In addition to the `medusa-react` library, you need the following libraries: -1. `react-query`: `medusa-react` is built on top of [React Query v3](https://react-query-v3.tanstack.com/). You’ll learn later in this reference how you can use Mutations and Queries with Medusa React. -2. `@medusajs/medusa`: The core Medusa package. This is used to import types used by Medusa React and while developing with it. +1\. `@tanstack/react-query`: `medusa-react` is built on top of [Tanstack Query](https://tanstack.com/query/latest/docs/react/overview). You’ll learn later in this reference how you can use Mutations and Queries with Medusa React. + +:::note + +Versions of Medusa React prior to v4.0.2 used React Query v3 instead of Tanstack Query. Check out [this upgrade guide] to learn how you can update your storefront. + +::: + +2\. `@medusajs/medusa`: The core Medusa package. This is used to import types used by Medusa React and while developing with it. :::info @@ -36,14 +43,14 @@ To use the hooks exposed by Medusa React, you need to include the `MedusaProvi The `MedusaProvider` requires two props: 1. `baseUrl`: The URL to your Medusa server -2. `queryClientProviderProps`: An object used to set the `react-query` client. The object requires a `client` property, which should be an instance of [QueryClient](https://react-query-v3.tanstack.com/reference/QueryClient). +2. `queryClientProviderProps`: An object used to set the Tanstack Query client. The object requires a `client` property, which should be an instance of [QueryClient](https://tanstack.com/query/v4/docs/react/reference/QueryClient). For example: ```tsx title=src/App.ts import { MedusaProvider } from "medusa-react" import Storefront from "./Storefront" -import { QueryClient } from "react-query" +import { QueryClient } from "@tanstack/react-query" import React from "react" const queryClient = new QueryClient() @@ -68,7 +75,7 @@ The `Storefront` component and its child components can now use hooks exposed by ### Queries -To fetch data from the Medusa server (in other words, perform `GET` requests), you can use [Queries](https://react-query-v3.tanstack.com/guides/queries). Query hooks simply wrap around react-query's `useQuery` hook to fetch data from your medusa server. +To fetch data from the Medusa server (in other words, perform `GET` requests), you can use [Queries](https://tanstack.com/query/v4/docs/react/guides/queries). Query hooks simply wrap around Tanstack Query's `useQuery` hook to fetch data from your medusa server. For example, to fetch products from your Medusa server: @@ -99,7 +106,7 @@ const Products = () => { export default Products ``` -In the example above, you import the `useProducts` hook from `medusa-react`. This hook, and every other query hook exposed by `medusa-react`, returns everything that `useQuery` [returns in react-query](https://react-query-v3.tanstack.com/reference/useQuery), except for the `data` field. +In the example above, you import the `useProducts` hook from `medusa-react`. This hook, and every other query hook exposed by `medusa-react`, returns everything that `useQuery` [returns in Tanstack Query](https://tanstack.com/query/v4/docs/react/reference/useQuery), except for the `data` field. Instead of the `data` field, the response data is flattened and is part of the hooks’ returned fields. In the example above, the List Products endpoint returns a `products` array. So, `useProducts` returns a `products` array along with other fields returned by `useQuery`. @@ -111,11 +118,11 @@ const { products } = useProducts({ }) ``` -You can learn more about using queries in [React Query’s documentation](https://react-query-v3.tanstack.com/guides/queries). +You can learn more about using queries in [Tanstack Query’s documentation](https://tanstack.com/query/v4/docs/react/guides/queries). ### Mutations -To create, update, or delete data on the Medusa server (in other words, perform `POST`, `PUT`, and `DELETE` requests), you can use [Mutations](https://react-query-v3.tanstack.com/guides/mutations). Mutation hooks wrap around react-query's `useMutation` to mutate data on your medusa server. +To create, update, or delete data on the Medusa server (in other words, perform `POST`, `PUT`, and `DELETE` requests), you can use [Mutations](https://tanstack.com/query/v4/docs/react/guides/mutations). Mutation hooks wrap around Tanstack Query's `useMutation` to mutate data on your medusa server. For example, to create a cart: @@ -148,13 +155,13 @@ const Cart = () => { export default Cart ``` -In the example above, you import the `useCreateCart` hook from `medusa-react`. This hook, and every other mutation hook exposed by `medusa-react`, returns everything that [useMutation](https://react-query-v3.tanstack.com/reference/useMutation) returns. You can also pass the same options you would pass to `useMutation` to mutation hooks exposed by `medusa-react`. +In the example above, you import the `useCreateCart` hook from `medusa-react`. This hook, and every other mutation hook exposed by `medusa-react`, returns everything that [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation) returns. You can also pass the same options you would pass to `useMutation` to mutation hooks exposed by `medusa-react`. To create a cart, you call the `createCart.mutate` method. In the underlying logic, this method sends a `POST` request to the Medusa server to create a cart. If the request accepts any parameters, they can be passed as parameters to the `mutate` request. For example: -```tsx +```ts createCart.mutate({ region_id, }) @@ -170,7 +177,7 @@ The example above does not store in the browser the ID of the cart created, so t Instead of using `mutate`, you can use `mutateAsync` to receive a Promise that resolves on success or throws on error. -Learn more about how you can use mutations in [React Query’s documentation](https://react-query-v3.tanstack.com/guides/mutations). +Learn more about how you can use mutations in [Tanstack Query’s documentation](https://tanstack.com/query/v4/docs/react/guides/mutations). --- @@ -349,7 +356,7 @@ For example: ```tsx title=src/App.ts import { CartProvider, MedusaProvider } from "medusa-react" import Storefront from "./Storefront" -import { QueryClient } from "react-query" +import { QueryClient } from "@tanstack/react-query" import React from "react" const queryClient = new QueryClient() @@ -439,7 +446,7 @@ For example: ```tsx title=src/App.ts import { SessionProvider, MedusaProvider } from "medusa-react" import Storefront from "./Storefront" -import { QueryClient } from "react-query" +import { QueryClient } from "@tanstack/react-query" import React from "react" const queryClient = new QueryClient() diff --git a/docs/content/usage/configurations.md b/docs/content/usage/configurations.md index 884a71a16c..ff0ba2a998 100644 --- a/docs/content/usage/configurations.md +++ b/docs/content/usage/configurations.md @@ -24,7 +24,7 @@ By default, Medusa loads environment variables from the system’s environment v :::info -This change in how environment variables are loaded was introduced in version 1.3.0. You can learn more in the [upgrade guide for version 1.3.0](../advanced/backend/upgrade-guides/1-3-0.md). +This change in how environment variables are loaded was introduced in version 1.3.0. You can learn more in the [upgrade guide for version 1.3.0](../advanced/backend/upgrade-guides/medusa-core/1-3-0.md). ::: diff --git a/packages/medusa-react/README.md b/packages/medusa-react/README.md index 12d79e079f..62e88b9c86 100644 --- a/packages/medusa-react/README.md +++ b/packages/medusa-react/README.md @@ -2,305 +2,4 @@ A React library providing a set of components, utilities, and hooks for interacting seamlessly with a Medusa backend and building custom React storefronts. -## Installation - -The library uses [react-query](https://react-query.tanstack.com/overview) as a solution for server-side state management and lists the library as a peer dependency. - -In order to install the package, run the following - -```bash -npm install medusa-react react-query @medusajs/medusa -# or -yarn add medusa-react react-query @medusajs/medusa -``` - -## Quick Start - -In order to use the hooks exposed by medusa-react, you will need to include the `MedusaProvider` somewhere up in your component tree. The `MedusaProvider` takes a `baseUrl` prop which should point to your Medusa server. Under the hood, `medusa-react` uses the `medusa-js` client library (built on top of axios) to interact with your server. - -In addition, because medusa-react is built on top of react-query, you can pass an object representing react-query's [QueryClientProvider](https://react-query.tanstack.com/reference/QueryClientProvider#_top) props, which will be passed along by `MedusaProvider`. - -```jsx -// App.tsx - -import * as React from "react" -import { QueryClient } from "@tanstack/react-query" -import { MedusaProvider } from "medusa-react" -import MyStorefront from "./my-storefront" - -// Your react-query's query client config -const queryClient = new QueryClient({ - defaultOptions: { - queries: { - refetchOnWindowFocus: false, - staleTime: 30000, - retry: 1, - }, - }, -}) - -const App = () => { - return ( - - - - ) -} - -export default App -``` - -The hooks exposed by `medusa-react` fall into two main categories: queries and mutations. - -### Queries - -[Queries](https://react-query.tanstack.com/guides/queries#_top) simply wrap around react-query's `useQuery` hook to fetch some data from your medusa server - -```jsx -// ./my-storefront.tsx -import * as React from "react" -import { useProducts } from "medusa-react" - -const MyStorefront = () => { - const { products, isLoading } = useProducts() - - return isLoading ? ( - - ) : ( - products.map((product) => ) - ) -} -``` - -In general, the queries will return everything react-query returns from [`useQuery`](https://react-query.tanstack.com/reference/useQuery#_top) except the `data` field, which will be flattened out. In addition, you can also access the HTTP response object returned from the `medusa-js` client including things like `status`, `headers`, etc. - -So, in other words, we can express what the above query returns as the following: - -```typescript -import { UseQueryResult } from "@tanstack/react-query" - -// This is what a Medusa server returns when you hit the GET /store/products endpoint -type ProductsResponse = { - products: Product[] - limit: number - offset: number -} - -// UseProductsQuery refers to what's returned by the useProducts hook -type UseProductsQuery = ProductsResponse & - Omit & { - response: { - status: number - statusText: string - headers: Record & { - "set-cookie"?: string[] - } - config: any - request?: any - } - } - -// More generally ... - -type QueryReturnType = APIResponse & - Omit & { - response: { - status: number - statusText: string - headers: Record & { - "set-cookie"?: string[] - } - config: any - request?: any - } - } -``` - -### Mutations - -[Mutations](https://react-query.tanstack.com/guides/mutations#_top) wrap around react-query's `useMutation` to mutate data and perform server-side effects on your medusa server. If you are not entirely familiar with this idea of "mutations", creating a cart would be a mutation because it creates a cart in your server (and database). Mutations also have to be invoked imperatively, meaning that calling for the mutation to take action, you will have to call a `mutate()` function returned from mutation hooks. - -```jsx -import * as React from "react" -import { useCreateCart } from "medusa-react" - -const CreateCartButton = () => { - const createCart = useCreateCart() - const handleClick = () => { - createCart.mutate({}) // create an empty cart - } - - return ( - - ) -} -``` - -The mutation hooks will return exactly what react-query's [`useMutation`](https://react-query.tanstack.com/reference/useMutation#_top) returns. In addition, the options you pass in to the hooks will be passed along to `useMutation`. - -### Utilities - -A set of utility functions are also exposed from the library to make your life easier when dealing with displaying money amounts - -#### `formatVariantPrice()` - -- `formatVariantPrice(params: FormatVariantPriceParams): string` - -```typescript -type FormatVariantPriceParams = { - variant: ProductVariantInfo - region: RegionInfo - includeTaxes?: boolean - minimumFractionDigits?: number - maximumFractionDigits?: number - locale?: string -} - -type ProductVariantInfo = Pick - -type RegionInfo = { - currency_code: string - tax_code: string - tax_rate: number -} -``` - -Given a variant and region, will return a string representing the localized amount (i.e: `$19.50`) - -The behavior of minimumFractionDigits and maximumFractionDigits is the same as the one explained by MDN [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). In fact, in order to convert the decimal amount, we use the browser's `Intl.NumberFormat` method. - -#### `computeVariantPrice()` - -- `computeVariantPrice(params: ComputeVariantPriceParams): number` - -```typescript -type ComputeVariantPriceParams = { - variant: ProductVariantInfo - region: RegionInfo - includeTaxes?: boolean -} -``` - -Determines a variant's price based on the region provided. Returns a decimal number representing the amount. - -#### `formatAmount()` - -- `formatAmount(params: FormatAmountParams): string` - -```typescript -type FormatAmountParams = { - amount: number - region: RegionInfo - includeTaxes?: boolean - minimumFractionDigits?: number - maximumFractionDigits?: number - locale?: string -} -``` - -Returns a localized string based on the input params representing the amount (i.e: "$10.99"). - -#### `computeAmount()` - -- `computeAmount(params: ComputeAmountParams): number` - -```typescript -type ComputeAmountParams = { - amount: number - region: RegionInfo - includeTaxes?: boolean -} -``` - -Takes an integer amount, a region, and includeTaxes boolean. Returns a decimal amount including (or excluding) taxes. - -### Context Providers (Experimental) - -In order to make building custom storefronts easier, we also expose a `SessionCartProvider` and a `CartProvider` . At first, the two sound very similar to each other, however, the main distinction between the two is that the `SessionCartProvider` never interacts with your medusa server. - -The main goal behind the provider is to manage the state related to your users' cart experience. In other words, the provider keeps track of the items users add to their cart and help you interact with those items through a set of helpful methods like `addItem`, `updateQuantity`, `removeItem` , etc. - -On the other hand the `CartProvider` makes use of some of the hooks already exposed by `medusa-react` to help you create a cart (on the medusa backend), start the checkout flow, authorize payment sessions, etc. It also manages one single global piece of state which represents a cart, exactly like the one created on your medusa backend. - -You can think of a `sessionCart` as a purely client-side lightweight cart, in other words, just a javascript object living in your browser, whereas `cart` is the entity which you have stored in your database. - -### SessionCart - -The first step to using the `SessionCartProvider` is by inserting it somewhere up in your component tree. - -```jsx -// App.tsx - -import * as React from "react" -import { QueryClient } from "@tanstack/react-query" -import { MedusaProvider, SessionCartProvider } from "medusa-react" -import MyStorefront from "./my-storefront" - -// Your react-query's query client config -const queryClient = new QueryClient({ - defaultOptions: { - queries: { - refetchOnWindowFocus: false, - staleTime: 30000, - retry: 1, - }, - }, -}) - -const App = () => { - return ( - - - - - - ) -} - -export default App -``` - -### Cart - -```jsx -// App.tsx - -import * as React from "react" -import { QueryClient } from "@tanstack/react-query" -import { MedusaProvider, CartProvider } from "medusa-react" -import MyStorefront from "./my-storefront" - -// Your react-query's query client config -const queryClient = new QueryClient({ - defaultOptions: { - queries: { - refetchOnWindowFocus: false, - staleTime: 30000, - retry: 1, - }, - }, -}) - -const App = () => { - return ( - - - - - - ) -} - -export default App -``` +Learn how to install and use it in [this documentation](https://docs.medusajs.com/medusa-react/overview). diff --git a/www/docs/docusaurus.config.js b/www/docs/docusaurus.config.js index 8dcfda82ad..2b0873de38 100644 --- a/www/docs/docusaurus.config.js +++ b/www/docs/docusaurus.config.js @@ -2,6 +2,7 @@ const path = require("path") const fs = require("fs") const docsPath = path.join(__dirname, "../../docs/content") const apisPath = path.join(__dirname, "../../docs/api") +const reverseSidebar = require('./src/utils/reverseSidebar') const algoliaAppId = process.env.ALGOLIA_APP_ID || "temp" const algoliaApiKey = process.env.ALGOLIA_API_KEY || "temp" @@ -33,7 +34,7 @@ const config = { apiKey: process.env.SEGMENT_API_KEY || "temp" } ], - require.resolve("docusaurus-plugin-image-zoom") + require.resolve("docusaurus-plugin-image-zoom"), ], themeConfig: { image: 'img/docs-banner.jpg', @@ -210,6 +211,10 @@ const config = { ], showLastUpdateTime: true, breadcrumbs: false, + async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) { + const sidebarItems = await defaultSidebarItemsGenerator(args); + return reverseSidebar(sidebarItems); + }, }, theme: { customCss: require.resolve("./src/css/custom.css") diff --git a/www/docs/netlify.toml b/www/docs/netlify.toml index 03b920b820..407bb4e164 100644 --- a/www/docs/netlify.toml +++ b/www/docs/netlify.toml @@ -84,4 +84,32 @@ [[redirects]] from = "/guides/checkouts" - to = "/advanced/storefront/how-to-implement-checkout-flow" \ No newline at end of file + to = "/advanced/storefront/how-to-implement-checkout-flow" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-7-3" + to="advanced/backend/upgrade-guides/medusa-core/1-7-3" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-7-1" + to="advanced/backend/upgrade-guides/medusa-core/1-7-1" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-7-0" + to="advanced/backend/upgrade-guides/medusa-core/1-7-0" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-6-1" + to="advanced/backend/upgrade-guides/medusa-core/1-6-1" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-3-8" + to="advanced/backend/upgrade-guides/medusa-core/1-3-8" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-3-6" + to="advanced/backend/upgrade-guides/medusa-core/1-3-6" + +[[redirects]] + from="/advanced/backend/upgrade-guides/1-3-0" + to="advanced/backend/upgrade-guides/medusa-core/1-3-0" \ No newline at end of file diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 9909b099a4..1ea583f512 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -183,45 +183,35 @@ module.exports = { }, items: [ { - type: "doc", - id: "advanced/backend/upgrade-guides/1-7-3", - label: "v1.7.3" + type: "category", + label: "Server", + items: [ + { + type: 'autogenerated', + dirName: 'advanced/backend/upgrade-guides/medusa-core' + } + ] }, { - type: "doc", - id: "advanced/backend/upgrade-guides/1-7-1", - label: "v1.7.1" + type: "category", + label: "Medusa React", + items: [ + { + type: 'autogenerated', + dirName: 'advanced/backend/upgrade-guides/medusa-react' + } + ] }, { - type: "doc", - id: "advanced/backend/upgrade-guides/1-7-0", - label: "v1.7.0" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/1-6-1", - label: "v1.6.1" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/1-3-8", - label: "v1.3.8" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/1-3-6", - label: "v1.3.6" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/1-3-0", - label: "v1.3.0" - }, - { - type: "doc", - id: "advanced/backend/upgrade-guides/admin/admin-vite", - label: "Medusa Admin: Vite" - }, + type: "category", + label: "Medusa Admin", + items: [ + { + type: 'autogenerated', + dirName: 'advanced/backend/upgrade-guides/admin' + } + ] + } ] }, { diff --git a/www/docs/src/utils/filterListItems.ts b/www/docs/src/utils/filterListItems.ts index 21c1e74e4f..e0c70cae3c 100644 --- a/www/docs/src/utils/filterListItems.ts +++ b/www/docs/src/utils/filterListItems.ts @@ -1,9 +1,28 @@ -export default function filterListItems (items: any[], pathPattern: string | RegExp) { +import { PropSidebarItem, PropSidebarItemLink } from '@docusaurus/plugin-content-docs' + +export default function filterListItems (items: PropSidebarItemLink[], pathPattern: string | RegExp): PropSidebarItemLink[] { + console.log(items) if (!items.length) { return items } let pattern = new RegExp(pathPattern) - return items.filter((item) => pattern.test(item.href)) + return items.filter((item: PropSidebarItemLink) => pattern.test(item.href)) +} + +/** + * Flatting a sidebar list moving items from category + * to links + */ +export function flattenList (items: PropSidebarItem[]): PropSidebarItem[] { + const newItems = items.map((item: PropSidebarItem) => { + if (item.type !== 'category') { + return item + } + + return item.items + }) + + return newItems.flat() } \ No newline at end of file diff --git a/www/docs/src/utils/reverseSidebar.js b/www/docs/src/utils/reverseSidebar.js new file mode 100644 index 0000000000..599b587fcf --- /dev/null +++ b/www/docs/src/utils/reverseSidebar.js @@ -0,0 +1,10 @@ +module.exports = function reverseSidebarItems(items) { + // Reverse items in categories + const result = items.map((item) => { + if (item.type === 'category' && item.customProps?.sort === 'desc') { + return {...item, items: reverseSidebarItems(item.items)}; + } + return item; + }); + return result; +} \ No newline at end of file