docs: added migration guide for Medusa React (#3066)
* docs: added migration guide for Medusa React * docs: fixed vale error
This commit is contained in:
Shahed Nasser
GitHub
@@ -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).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -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 (
|
||||
<MedusaProvider
|
||||
queryClientProviderProps={{ client: queryClient }}
|
||||
baseUrl="http://localhost:9000"
|
||||
>
|
||||
<MyStorefront />
|
||||
</MedusaProvider>
|
||||
)
|
||||
}
|
||||
|
||||
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 ? (
|
||||
<Spinner />
|
||||
) : (
|
||||
products.map((product) => <Product product={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<UseQueryResult, "data"> & {
|
||||
response: {
|
||||
status: number
|
||||
statusText: string
|
||||
headers: Record<string, string> & {
|
||||
"set-cookie"?: string[]
|
||||
}
|
||||
config: any
|
||||
request?: any
|
||||
}
|
||||
}
|
||||
|
||||
// More generally ...
|
||||
|
||||
type QueryReturnType = APIResponse &
|
||||
Omit<UseQueryResult, "data"> & {
|
||||
response: {
|
||||
status: number
|
||||
statusText: string
|
||||
headers: Record<string, string> & {
|
||||
"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 (
|
||||
<Button isLoading={createCart.isLoading} onClick={handleClick}>
|
||||
Create cart
|
||||
</Button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
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<ProductVariant, "prices">
|
||||
|
||||
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 (
|
||||
<MedusaProvider
|
||||
queryClientProviderProps={{ client: queryClient }}
|
||||
baseUrl="http://localhost:9000"
|
||||
>
|
||||
<SessionCartProvider>
|
||||
<MyStorefront />
|
||||
</SessionCartProvider>
|
||||
</MedusaProvider>
|
||||
)
|
||||
}
|
||||
|
||||
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 (
|
||||
<MedusaProvider
|
||||
queryClientProviderProps={{ client: queryClient }}
|
||||
baseUrl="http://localhost:9000"
|
||||
>
|
||||
<CartProvider>
|
||||
<MyStorefront />
|
||||
</CartProvider>
|
||||
</MedusaProvider>
|
||||
)
|
||||
}
|
||||
|
||||
export default App
|
||||
```
|
||||
Learn how to install and use it in [this documentation](https://docs.medusajs.com/medusa-react/overview).
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -84,4 +84,32 @@
|
||||
|
||||
[[redirects]]
|
||||
from = "/guides/checkouts"
|
||||
to = "/advanced/storefront/how-to-implement-checkout-flow"
|
||||
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"
|
||||
@@ -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'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@@ -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()
|
||||
}
|
||||
10
www/docs/src/utils/reverseSidebar.js
Normal file
10
www/docs/src/utils/reverseSidebar.js
Normal file
@@ -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;
|
||||
}
|
||||
Reference in New Issue
Block a user