docs: update storefront development guides to use JS SDK [1] (#11991)
* docs: update storefront development guides to use JS SDK [1] * build and lint fixes * fix links * fix links
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
82d774b395
commit
e950e2b2d2
15 files changed
+12381
-12993
No files matched your search
@@ -7,12 +7,20 @@ tags:
|
||||
import { CodeTabs, CodeTab } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Region Context in Storefront`,
|
||||
title: `Region React Context in Storefront`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
Throughout your storefront, you'll need to access the selected region to perform different actions, such as retrieve product's prices in the selected region.
|
||||
In this guide, you'll learn how to create a region context in your React storefront.
|
||||
|
||||
Throughout your storefront, you'll need to access the customer's selected region to perform different actions, such as retrieve product's prices in the selected region.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
To learn how to allow customers to select their region, refer to the [Store Selected Region in Storefront](../store-retrieve-region/page.mdx) guide.
|
||||
|
||||
</Note>
|
||||
|
||||
So, if your storefront is React-based, create a region context and add it at the top of your components tree. Then, you can access the selected region anywhere in your storefront.
|
||||
|
||||
@@ -20,15 +28,21 @@ So, if your storefront is React-based, create a region context and add it at the
|
||||
|
||||
For example, create the following file that exports a `RegionProvider` component and a `useRegion` hook:
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Learn how to install and configure the JS SDK in the [JS SDK documentation](../../../js-sdk/page.mdx).
|
||||
|
||||
</Note>
|
||||
|
||||
export const highlights = [
|
||||
["12", "region", "Expose region to children of the context provider."],
|
||||
["13", "setRegion", "Allow the context provider's children to change the selected region."],
|
||||
["24", "RegionProvider", "The provider component to use in your component tree."],
|
||||
["32", "", "If a region is set, set its ID in the local storage again in case it changed."],
|
||||
["39", "regionId", "Retrieve the selected region from the `localStorage`."],
|
||||
["42", "fetch", "If no region is selected, retrieve the list of regions from the Medusa application and select the first one."],
|
||||
["54", "fetch", "If a region is selected, retrieve it from the Medusa application."],
|
||||
["77", "useRegion", "The hook that child components of the provider use to access the region."]
|
||||
["13", "region", "Expose region to children of the context provider."],
|
||||
["14", "setRegion", "Allow the context provider's children to change the selected region."],
|
||||
["25", "RegionProvider", "The provider component to use in your component tree."],
|
||||
["31", "", "If a region is set, set its ID in the local storage again in case it changed."],
|
||||
["38", "regionId", "Retrieve the selected region from the `localStorage`."],
|
||||
["41", "list", "If no region is selected, retrieve the list of regions from the Medusa application and select the first one."],
|
||||
["47", "retrieve", "If a region is selected, retrieve it from the Medusa application."],
|
||||
["6", "useRegion", "The hook that child components of the provider use to access the region."]
|
||||
]
|
||||
|
||||
```tsx highlights={highlights}
|
||||
@@ -41,6 +55,7 @@ import {
|
||||
useState,
|
||||
} from "react"
|
||||
import { HttpTypes } from "@medusajs/types"
|
||||
import { sdk } from "../lib/sdk"
|
||||
|
||||
type RegionContextType = {
|
||||
region?: HttpTypes.StoreRegion
|
||||
@@ -55,9 +70,7 @@ type RegionProviderProps = {
|
||||
children: React.ReactNode
|
||||
}
|
||||
|
||||
export const RegionProvider = (
|
||||
{ children }: RegionProviderProps
|
||||
) => {
|
||||
export const RegionProvider = ({ children }: RegionProviderProps) => {
|
||||
const [region, setRegion] = useState<
|
||||
HttpTypes.StoreRegion
|
||||
>()
|
||||
@@ -73,25 +86,13 @@ export const RegionProvider = (
|
||||
const regionId = localStorage.getItem("region_id")
|
||||
if (!regionId) {
|
||||
// retrieve regions and select the first one
|
||||
fetch(`http://localhost:9000/store/regions`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || "temp",
|
||||
},
|
||||
})
|
||||
.then((res) => res.json())
|
||||
sdk.store.region.list()
|
||||
.then(({ regions }) => {
|
||||
setRegion(regions[0])
|
||||
})
|
||||
} else {
|
||||
// retrieve selected region
|
||||
fetch(`http://localhost:9000/store/regions/${regionId}`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || "temp",
|
||||
},
|
||||
})
|
||||
.then((res) => res.json())
|
||||
sdk.store.region.retrieve(regionId)
|
||||
.then(({ region: dataRegion }) => {
|
||||
setRegion(dataRegion)
|
||||
})
|
||||
@@ -163,9 +164,7 @@ export default function RootLayout({
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Use useRegion Hook
|
||||
### Use useRegion Hook
|
||||
|
||||
Now, you can use the `useRegion` hook in child components of `RegionProvider`.
|
||||
|
||||
|
||||
@@ -12,31 +12,27 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll learn how to retrieve the list of regions in your storefront.
|
||||
|
||||
<Note title="Good to know">
|
||||
|
||||
A region is a geographical area that you sell your products in. In your storefront, you should display regions to your customers, allowing them to select their region to see prices, taxes, and payment methods specific to their region.
|
||||
|
||||
</Note>
|
||||
|
||||
To list regions in your storefront, send a request to the [List Regions API route](!api!/store#regions_getregions):
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Learn how to install and configure the JS SDK in the [JS SDK documentation](../../../js-sdk/page.mdx).
|
||||
|
||||
</Note>
|
||||
|
||||
<CodeTabs group="store-request">
|
||||
<CodeTab label="Fetch API" value="fetch">
|
||||
|
||||
```ts
|
||||
fetch(`http://localhost:9000/store/regions`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || "temp",
|
||||
},
|
||||
})
|
||||
.then((res) => res.json())
|
||||
.then(({ regions }) => {
|
||||
// use regions...
|
||||
console.log(regions)
|
||||
})
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="React" value="react">
|
||||
|
||||
export const highlights = [
|
||||
["17"], ["18"], ["19"], ["20"], ["21"], ["22"], ["23"], ["24"],
|
||||
["25"], ["26"], ["27"]
|
||||
["18"], ["19"], ["20"], ["21"], ["22"]
|
||||
]
|
||||
|
||||
```tsx highlights={highlights}
|
||||
@@ -44,6 +40,7 @@ export const highlights = [
|
||||
|
||||
import { useEffect, useState } from "react"
|
||||
import { HttpTypes } from "@medusajs/types"
|
||||
import { sdk } from "../../lib/sdk"
|
||||
|
||||
export default function Regions() {
|
||||
const [loading, setLoading] = useState(true)
|
||||
@@ -56,13 +53,7 @@ export const highlights = [
|
||||
return
|
||||
}
|
||||
|
||||
fetch(`http://localhost:9000/store/regions`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || "temp",
|
||||
},
|
||||
})
|
||||
.then((res) => res.json())
|
||||
sdk.store.region.list()
|
||||
.then(({ regions: dataRegions }) => {
|
||||
setRegions(dataRegions)
|
||||
setLoading(false)
|
||||
@@ -85,7 +76,20 @@ export const highlights = [
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="JS SDK" value="js-sdk">
|
||||
|
||||
```ts
|
||||
sdk.store.region.list()
|
||||
.then(({ regions: dataRegions }) => {
|
||||
setRegions(dataRegions)
|
||||
setLoading(false)
|
||||
})
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
</CodeTabs>
|
||||
|
||||
The response has a `regions` field, which is an array of [regions](!api!/store#regions_region_schema).
|
||||
|
||||
Next, you can learn how to allow the customer to select a region in the [Store and Retrieve Region guide](../store-retrieve-region/page.mdx).
|
||||
+27
-14
@@ -5,16 +5,24 @@ tags:
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `Store and Retrieve Region`,
|
||||
title: `Store Selected Region in Storefront`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn how to store a customer's region's ID and retrieve the selected region.
|
||||
In this guide, you'll learn how to store a customer's selected region in your storefront, then retrieve it for later use.
|
||||
|
||||
## Why Store and Retrieve Region?
|
||||
|
||||
In your store, prices, taxes, and available payment methods can vary between regions. So, you should allow customers to select their region to see the correct prices, taxes, and payment methods.
|
||||
|
||||
---
|
||||
|
||||
## Store Selected Region ID
|
||||
|
||||
When the customer selects their region, for example, from a dropdown, store that region's ID in the `localStorage`.
|
||||
To allow the customer to select a region, you should show them the list of regions as explained in the [List Regions](../list/page.mdx) guide. You can show them in a select input, for example.
|
||||
|
||||
Then, once the customer selects their region, store that region's ID in the `localStorage`.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -22,7 +30,7 @@ For example:
|
||||
localStorage.setItem("region_id", region.id)
|
||||
```
|
||||
|
||||
Then, you retrieve it later using the `localSorage.getItem` method later:
|
||||
Then, you can retrieve it later using the `localSorage.getItem` method:
|
||||
|
||||
```ts
|
||||
const regionId = localStorage.getItem("region_id")
|
||||
@@ -30,22 +38,27 @@ const regionId = localStorage.getItem("region_id")
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Selected Region
|
||||
## Retrieve Selected Region's Details
|
||||
|
||||
To retrieve the selected region, use the [Retrieve Region API route](!api!/store#regions_getregionsid):
|
||||
As you build your storefront, you may need to retrieve the full details of a region. For example, to get the region's currency code.
|
||||
|
||||
To retrieve the selected region's details from Medusa, use the [Retrieve Region API route](!api!/store#regions_getregionsid):
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Learn how to install and configure the JS SDK in the [JS SDK documentation](../../../js-sdk/page.mdx).
|
||||
|
||||
</Note>
|
||||
|
||||
```ts
|
||||
const regionId = localStorage.getItem("region_id")
|
||||
|
||||
fetch(`http://localhost:9000/store/regions/${regionId}`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || "temp",
|
||||
},
|
||||
})
|
||||
.then((res) => res.json())
|
||||
sdk.store.region.retrieve(regionId)
|
||||
.then(({ region }) => {
|
||||
// do something with region.
|
||||
console.log(region)
|
||||
})
|
||||
```
|
||||
|
||||
The response has a `regions` field, which is an array of [regions](!api!/store#regions_region_schema).
|
||||
|
||||
If you're using React, it's then recommended to create a context that stores the region details and make it available to all components in your application, as explained in the [Region React Context in Storefront](../context/page.mdx) guide.
|
||||
Reference in new issue
Block a user