diff --git a/www/apps/book/app/storefront-development/page.mdx b/www/apps/book/app/storefront-development/page.mdx index 8bc0ea00f3..1b3f8f71d2 100644 --- a/www/apps/book/app/storefront-development/page.mdx +++ b/www/apps/book/app/storefront-development/page.mdx @@ -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. + + + +To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development) in the Learning Resources documentation. + + diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index f23ca461d5..18988ab76f 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -232,10 +232,6 @@ export const sidebar = sidebarAttachHrefCommonOptions( path: "/storefront-development/nextjs-starter", title: "Next.js Starter", }, - { - path: "/storefront-development/tips", - title: "Storefront Tips", - }, ], }, { diff --git a/www/apps/resources/app/storefront-development/page.mdx b/www/apps/resources/app/storefront-development/page.mdx new file mode 100644 index 0000000000..d150890cfd --- /dev/null +++ b/www/apps/resources/app/storefront-development/page.mdx @@ -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. + + \ No newline at end of file diff --git a/www/apps/resources/app/storefront-development/regions/list/page.mdx b/www/apps/resources/app/storefront-development/regions/list/page.mdx new file mode 100644 index 0000000000..a637b5071d --- /dev/null +++ b/www/apps/resources/app/storefront-development/regions/list/page.mdx @@ -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): + + + + + ```ts + fetch(`http://localhost:9000/store/regions`, { + credentials: "include" + }) + .then((res) => res.json()) + .then(({ regions }) => { + // use regions... + console.log(regions) + }) + ``` + + + + +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 ( +
+ {loading && Loading...} + {!loading && regions.length === 0 && No regions found.} + {!loading && regions.length > 0 && ( +
    + {regions.map((region) => ( +
  • {region.name}
    • + ))} +
+ )} +
+ ); + } + ``` + + + + +{/* TODO add a link to regions object in API reference (once available). */} + +The response has a `regions` field, which is an array of regions. diff --git a/www/apps/resources/app/storefront-development/regions/page.mdx b/www/apps/resources/app/storefront-development/regions/page.mdx new file mode 100644 index 0000000000..f18c51424d --- /dev/null +++ b/www/apps/resources/app/storefront-development/regions/page.mdx @@ -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). + + \ No newline at end of file diff --git a/www/apps/resources/app/storefront-development/regions/store-retrieve-region/page.mdx b/www/apps/resources/app/storefront-development/regions/store-retrieve-region/page.mdx new file mode 100644 index 0000000000..202e74b6af --- /dev/null +++ b/www/apps/resources/app/storefront-development/regions/store-retrieve-region/page.mdx @@ -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) +}) +``` diff --git a/www/apps/book/app/storefront-development/tips/page.mdx b/www/apps/resources/app/storefront-development/tips/page.mdx similarity index 68% rename from www/apps/book/app/storefront-development/tips/page.mdx rename to www/apps/resources/app/storefront-development/tips/page.mdx index d0f4db804d..13f8409089 100644 --- a/www/apps/book/app/storefront-development/tips/page.mdx +++ b/www/apps/resources/app/storefront-development/tips/page.mdx @@ -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 -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). diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index 8d0af1b1ce..e06436ad5b 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/www/apps/resources/generated/files-map.mjs @@ -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" diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs index 62549a363f..a167decc22 100644 --- a/www/apps/resources/generated/sidebar.mjs +++ b/www/apps/resources/generated/sidebar.mjs @@ -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, diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs index 7fd6f163c0..5d2164de7a 100644 --- a/www/apps/resources/sidebar.mjs +++ b/www/apps/resources/sidebar.mjs @@ -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,