docs: added storefront regions guides (#7623)

2024-06-09 16:19:09 +03:00
parent 6946814944
commit 46c5c5fe28
10 changed files with 261 additions and 14 deletions
@@ -10,4 +10,10 @@ In the next chapters, you’ll learn about building a storefront for your Medusa

 Storefronts are built separately from the Medusa application. They interact with the Medusa application through the Store API routes.

-You're free to choose how to build your storefront. You can start with our Next.js starter storefront or build a storefront from scratch using your preferred framework or tech stack. Both of these approaches are explained in the next chapters.
+You're free to choose how to build your storefront. You can start with our Next.js starter storefront or build a storefront from scratch using your preferred framework or tech stack.
+
+<Note title="Tip">
+
+To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development) in the Learning Resources documentation.
+
+</Note>
@@ -232,10 +232,6 @@ export const sidebar = sidebarAttachHrefCommonOptions(
          path: "/storefront-development/nextjs-starter",
          title: "Next.js Starter",
        },
-        {
-          path: "/storefront-development/tips",
-          title: "Storefront Tips",
-        },
      ],
    },
    {
@@ -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)
+})
+```
@@ -1,10 +1,10 @@
 export const metadata = {
-  title: `${pageNumber} Storefront Development Tips`,
+  title: `Storefront Development Tips`,
 }

 # {metadata.title}

-In this chapter, you’ll find tips to help you build a storefront.
+In this document, you’ll find tips useful when building a storefront.

 ## Connect to the Medusa Application

@@ -16,9 +16,21 @@ Support for Medusa v2 in Medusa React and the JS Client is coming soon.

 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.
- **For other frontend technologies**:  interact directly with the Medusa application by sending requests to its [Store REST APIs](https://docs.medusajs.com/api/store).
+
+---
+
+## 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
+```

 ---

@@ -54,10 +66,6 @@ Products, carts, and orders are associated with a sales channel. If you don’t

 </Note>

-Publishable API keys are provided by the [API key commerce module](!resources!/commerce-modules/api-key).
+{/* TODO replace link with admin how-to guide once available. */}

---
-
-## Implement Commerce Functionalities
-
-Refer to the [Commerce Modules reference](!resources!/commerce-modules) for how-to guides on common commerce functionalities.
+Create a publishable API key either using the Medusa Admin or the [Admin API routes](!api!/admin#api-keys_postapikeys).
@@ -871,6 +871,26 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/references/[...slug]/page.tsx",
    "pathname": "/references/[...slug]"
  },
+  {
+    "filePath": "/www/apps/resources/app/storefront-development/page.mdx",
+    "pathname": "/storefront-development"
+  },
+  {
+    "filePath": "/www/apps/resources/app/storefront-development/regions/list/page.mdx",
+    "pathname": "/storefront-development/regions/list"
+  },
+  {
+    "filePath": "/www/apps/resources/app/storefront-development/regions/page.mdx",
+    "pathname": "/storefront-development/regions"
+  },
+  {
+    "filePath": "/www/apps/resources/app/storefront-development/regions/store-retrieve-region/page.mdx",
+    "pathname": "/storefront-development/regions/store-retrieve-region"
+  },
+  {
+    "filePath": "/www/apps/resources/app/storefront-development/tips/page.mdx",
+    "pathname": "/storefront-development/tips"
+  },
  {
    "filePath": "/www/apps/resources/app/troubleshooting/_s3-plugin-acl-error/page.mdx",
    "pathname": "/troubleshooting/_s3-plugin-acl-error"
@@ -7096,6 +7096,45 @@ export const generatedSidebar = [
      }
    ]
  },
+  {
+    "loaded": true,
+    "isPathHref": true,
+    "path": "/storefront-development",
+    "title": "Storefront Development",
+    "hasTitleStyling": true,
+    "isChildSidebar": true,
+    "children": [
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "path": "/storefront-development/tips",
+        "title": "Tips",
+        "children": []
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "path": "/storefront-development/regions",
+        "title": "Regions",
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "path": "/storefront-development/regions/list",
+            "title": "List Regions",
+            "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "path": "/storefront-development/regions/store-retrieve-region",
+            "title": "Store and Retrieve Regions",
+            "children": []
+          }
+        ]
+      }
+    ]
+  },
  {
    "loaded": true,
    "isPathHref": true,
@@ -1781,6 +1781,32 @@ export const sidebar = sidebarAttachHrefCommonOptions([
      },
    ],
  },
+  {
+    path: "/storefront-development",
+    title: "Storefront Development",
+    hasTitleStyling: true,
+    isChildSidebar: true,
+    children: [
+      {
+        path: "/storefront-development/tips",
+        title: "Tips",
+      },
+      {
+        path: "/storefront-development/regions",
+        title: "Regions",
+        children: [
+          {
+            path: "/storefront-development/regions/list",
+            title: "List Regions",
+          },
+          {
+            path: "/storefront-development/regions/store-retrieve-region",
+            title: "Store and Retrieve Regions",
+          },
+        ],
+      },
+    ],
+  },
  {
    title: "Configurations",
    hasTitleStyling: true,