docs: added storefront regions guides (#7623)

2024-06-09 15:19:09 +02:00
parent 6946814944
commit 46c5c5fe28
10 changed files with 261 additions and 14 deletions
@@ -0,0 +1,11 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Storefront Development Guides`,
+}
+
+# {metadata.title}
+
+This section of the documentation holds guides to help you build a storefront for your Medusa application.
+
+<ChildDocs />
@@ -0,0 +1,80 @@
+import { CodeTabs, CodeTab } from "docs-ui"
+
+export const metadata = {
+  title: `List Regions in Storefront`,
+}
+
+# {metadata.title}
+
+To list regions in your storefront, send a request to the [List Regions API route](!api!/store#regions_getregions):
+
+<CodeTabs group="store-request">
+  <CodeTab label="Fetch API" value="fetch">
+
+  ```ts
+  fetch(`http://localhost:9000/store/regions`, {
+    credentials: "include"
+  })
+  .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"]
+]
+
+  ```tsx highlights={highlights}
+  "use client" // include with Next.js 13+
+
+  import { useEffect, useState } from "react";
+  import { HttpTypes } from "@medusajs/types"
+
+  export default function Regions() {
+    const [loading, setLoading] = useState(true)
+    const [regions, setRegions] = useState<
+      HttpTypes.StoreRegion[]
+    >([])
+
+    useEffect(() => {
+      if (!loading) {
+        return 
+      }
+
+      fetch(`http://localhost:9000/store/regions`, {
+        credentials: "include"
+      })
+      .then((res) => res.json())
+      .then(({ regions: dataRegions }) => {
+        setRegions(dataRegions)
+        setLoading(false)
+      })
+    }, [loading])
+
+    return (
+      <div>
+        {loading && <span>Loading...</span>}
+        {!loading && regions.length === 0 && <span>No regions found.</span>}
+        {!loading && regions.length > 0 && (
+          <ul>
+            {regions.map((region) => (
+              <li key={region.id}>{region.name}</li>
+            ))}
+          </ul>
+        )}
+      </div>
+    );
+  }
+  ```
+
+  </CodeTab>
+</CodeTabs>
+
+{/* TODO add a link to regions object in API reference (once available). */}
+
+The response has a `regions` field, which is an array of regions.
@@ -0,0 +1,19 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Regions in Storefront`,
+}
+
+# {metadata.title}
+
+A customer chooses their region in a storefront. The selected region is later used when retrieving prices for products and during checkout.
+
+In the storefront, you implement the following:
+
+- Show customers available regions, with ability to select their region.
+- Store selected region in local storage.
+- Pass the selected region's ID in other requests, such as when retrieving products, to retrieve the relevant price.
+
+The first two points are explained in the following guides, and the last one is explained in guides relevant to the topic (for example, the guide explaining how to retrieve products).
+
+<ChildDocs type="item" onlyTopLevel={true} />
@@ -0,0 +1,42 @@
+export const metadata = {
+  title: `Store and Retrieve Region`,
+}
+
+# {metadata.title}
+
+In this document, you'll learn how to store a customer's region's ID and retrieve the selected region.
+
+## Store Selected Region ID
+
+When the customer selects their region, for example, from a dropdown, store that region's ID in the `localstorage`.
+
+For example:
+
+```ts
+localStorage.setItem("region_id", region.id)
+```
+
+Then, you retrieve it later using the `localSorage.getItem` method later:
+
+```ts
+const regionId = localStorage.getItem("region_id")
+```
+
+---
+
+## Retrieve Selected Region
+
+To retrieve the selected region, use the [Retrieve Region API route](!api!/store#regions_getregionsid):
+
+```ts
+const regionId = localStorage.getItem("region_id")
+
+fetch(`http://localhost:9000/store/regions/${regionId}`, {
+  credentials: "include"
+})
+.then((res) => res.json())
+.then(({ region }) => {
+  // do something with region.
+  console.log(region)
+})
+```
@@ -0,0 +1,71 @@
+export const metadata = {
+  title: `Storefront Development Tips`,
+}
+
+# {metadata.title}
+
+In this document, you’ll find tips useful when building a storefront.
+
+## Connect to the Medusa Application
+
+<Note type="soon">
+
+Support for Medusa v2 in Medusa React and the JS Client is coming soon.
+
+</Note>
+
+To send requests from the storefront to the Medusa application’s Store API Routes, you have three options:
+
+- **For other frontend technologies**: interact directly with the Medusa application by sending requests to its [Store REST APIs](https://docs.medusajs.com/api/store).
+- **For React-based storefronts**: use Medusa React. It provides you with the necessary hooks to retrieve or manipulate data from your Medusa application.
+- **For JavaScript frameworks**: use Medusa’s JavaScript Client in any JavaScript framework. This NPM package facilitates interacting with the backend’s REST APIs.
+
+---
+
+## Install Types Package
+
+The `@medusajs/types` package provide API routes' request and response types.
+
+If you're not using the JS Client or Medusa React, install `@medusajs/types` to use the correct request and response types:
+
+```bash npm2yarn
+npm install @medusajs/types@preview
+```
+
+---
+
+## Configure CORS
+
+The Medusa application’s API routes are guarded by a CORS middleware. Make sure to set the `storeCors` property of the `http` configuration in `medusa-config.js` to the storefront’s URL.
+
+For example:
+
+```js title="medusa-config.js"
+module.exports = defineConfig({
+  projectConfig: {
+    http: {
+      storeCors: "http://localhost:3000",
+      // ...
+    }
+  }
+  // ...
+})
+```
+
+---
+
+## Use Publishable API Keys
+
+Publishable API keys specify the scope of a request. Admin users create them, and they can only be used on the client-side, such as in a storefront.
+
+Publishable API keys are associated with sales channels. Then, when the publishable API key is passed in the header of a request, the Medusa application automatically infers what sales channel is being used.
+
+<Note>
+
+Products, carts, and orders are associated with a sales channel. If you don’t specify a sales channel or a publishable API key, the products, carts, and orders are associated with the default sales channel.
+
+</Note>
+
+{/* TODO replace link with admin how-to guide once available. */}
+
+Create a publishable API key either using the Medusa Admin or the [Admin API routes](!api!/admin#api-keys_postapikeys).