From 57bb391146265c3c688b6d3f6ae7dc81945070bd Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 17 Aug 2023 20:37:40 +0300 Subject: [PATCH] docs: added new recipes (#4793) * added new recipes * added more recipes --- .../content/development/entities/overview.mdx | 3 + .../content/development/plugins/create.mdx | 5 + .../content/development/plugins/overview.mdx | 3 + www/docs/content/recipes/index.mdx | 16 +- www/docs/content/storefront/roadmap.mdx | 5 + .../components/LearningPath/List/index.tsx | 35 +++ .../components/LearningPath/Steps/index.tsx | 102 +++---- .../src/components/LearningPath/index.tsx | 6 +- .../Notification/Container/index.tsx | 4 +- .../components/Notification/Item/index.tsx | 4 +- .../src/hooks/use-current-learning-path.tsx | 1 + www/docs/src/utils/learning-paths.tsx | 271 +++++++++++++++++- 12 files changed, 392 insertions(+), 63 deletions(-) create mode 100644 www/docs/src/components/LearningPath/List/index.tsx diff --git a/www/docs/content/development/entities/overview.mdx b/www/docs/content/development/entities/overview.mdx index c19c9f31f5..e5d93d3647 100644 --- a/www/docs/content/development/entities/overview.mdx +++ b/www/docs/content/development/entities/overview.mdx @@ -4,6 +4,7 @@ description: 'Learn what entities are in Medusa. There are entities defined in t import DocCardList from '@theme/DocCardList'; import Icons from '@theme/Icon'; +import LearningPath from '@site/src/components/LearningPath'; # Entities @@ -17,6 +18,8 @@ Aside from the entities in the Medusa core package, you can also create custom e Entities are based on [Typeorm’s Entities](https://typeorm.io/entities) and use Typeorm decorators. Each entity also require a [repository](./repositories.md) to be created. A repository provides basic methods to access and manipulate the entity's data. + + --- ## Base Entities diff --git a/www/docs/content/development/plugins/create.mdx b/www/docs/content/development/plugins/create.mdx index 2fc561fa57..7d48618030 100644 --- a/www/docs/content/development/plugins/create.mdx +++ b/www/docs/content/development/plugins/create.mdx @@ -5,11 +5,16 @@ addHowToData: true import DocCardList from '@theme/DocCardList'; import Icons from '@theme/Icon'; +import LearningPath from '@site/src/components/LearningPath'; # How to Create a Plugin In this document, you’ll learn how to create a plugin and some tips for develoment. If you’re interested to learn more about what plugins are and where to find available official and community plugins, check out the [overview document](./overview.mdx). +Alternatively, you can follow this recipe to create a plugin with step-by-step guidance. + + + ## Prerequisites You must have an existing Medusa project that you want to create the plugin with. diff --git a/www/docs/content/development/plugins/overview.mdx b/www/docs/content/development/plugins/overview.mdx index 8c1467860a..c17491306c 100644 --- a/www/docs/content/development/plugins/overview.mdx +++ b/www/docs/content/development/plugins/overview.mdx @@ -4,6 +4,7 @@ description: 'Learn what Plugins are and how they are used in Medusa. Plugins ar import DocCardList from '@theme/DocCardList'; import Icons from '@theme/Icon'; +import LearningPath from '@site/src/components/LearningPath'; # Plugins @@ -23,6 +24,8 @@ Plugins run within the same process as the core Medusa backend eliminating the n Plugins can contain customizations to the Medusa backend or the admin dashboard. + + --- ## Using Existing Plugins diff --git a/www/docs/content/recipes/index.mdx b/www/docs/content/recipes/index.mdx index 43ca3988ef..b62cde35f3 100644 --- a/www/docs/content/recipes/index.mdx +++ b/www/docs/content/recipes/index.mdx @@ -3,6 +3,7 @@ import DocCard from '@theme/DocCard'; import Icons from '@theme/Icon'; import Feedback from '@site/src/components/Feedback'; import LearningPath from '@site/src/components/LearningPath'; +import LearningPathList from '@site/src/components/LearningPath/List'; import LargeCard from '@site/src/components/LargeCard'; import Button from '@site/src/components/Button'; @@ -60,15 +61,26 @@ Follow this guide if you want to implement subscription-based purhcases with Med } }} /> +--- + +## Other Recipes + +This section includes general recipes available to guide you through your development with Medusa. + + + ---- - ## Can't find your path? diff --git a/www/docs/content/storefront/roadmap.mdx b/www/docs/content/storefront/roadmap.mdx index 399fd159d0..d16d0af568 100644 --- a/www/docs/content/storefront/roadmap.mdx +++ b/www/docs/content/storefront/roadmap.mdx @@ -5,6 +5,7 @@ description: 'Learn about the different resources you need and the general steps import DocCardList from '@theme/DocCardList'; import DocCard from '@theme/DocCard'; import Icons from '@theme/Icon'; +import LearningPath from '@site/src/components/LearningPath'; # Build Your Own Storefront Roadmap @@ -16,6 +17,10 @@ Although Medusa provides a [Next.js Starter Template](../starters/nextjs-medusa- This guide provides a roadmap that can guide you into how you can build your own storefront, regardless of what tools you’re using. +You can instead follow this recipe that will guide you through implementing features in your storefront step-by-step. + + + --- ## Connect to the Backend diff --git a/www/docs/src/components/LearningPath/List/index.tsx b/www/docs/src/components/LearningPath/List/index.tsx new file mode 100644 index 0000000000..2012c69a42 --- /dev/null +++ b/www/docs/src/components/LearningPath/List/index.tsx @@ -0,0 +1,35 @@ +import React, { useMemo } from "react" +import { getLearningPaths } from "../../../utils/learning-paths" +import LearningPath from ".." + +type LearningPathListProps = { + ignore?: string[] +} & React.AllHTMLAttributes + +const LearningPathList: React.FC = ({ ignore = [] }) => { + const paths = useMemo(() => { + const paths = getLearningPaths() + ignore.forEach((pathName) => { + const pathIndex = paths.findIndex((path) => path.name === pathName) + if (pathIndex !== -1) { + paths.splice(pathIndex, 1) + } + }) + + return paths + }, [ignore]) + + return ( +
+ {paths.map((path, index) => ( + + ))} +
+ ) +} + +export default LearningPathList diff --git a/www/docs/src/components/LearningPath/Steps/index.tsx b/www/docs/src/components/LearningPath/Steps/index.tsx index f3844f8c34..1da2fb9346 100644 --- a/www/docs/src/components/LearningPath/Steps/index.tsx +++ b/www/docs/src/components/LearningPath/Steps/index.tsx @@ -20,62 +20,64 @@ const LearningPathSteps: React.FC = ({ ...rest }) => { } return ( -
- {path.steps.map((step, index) => ( -
-
-
- {index === currentStep && ( - - )} - {index < currentStep && ( - - )} - {index > currentStep && } -
- - {step.title} - -
- {index === currentStep && ( + <> +
+ {path.steps.map((step, index) => ( +
-
-
+ {index === currentStep && ( + + )} + {index < currentStep && ( + + )} + {index > currentStep && } +
+ - {step.descriptionJSX ?? step.description} -
+ {step.title} +
- )} - {index < currentStep && ( - { - e.preventDefault() - goToStep(index) - }} - /> - )} -
- ))} + {index === currentStep && ( +
+
+
+ {step.descriptionJSX ?? step.description} +
+
+ )} + {index < currentStep && ( + { + e.preventDefault() + goToStep(index) + }} + /> + )} +
+ ))} +
- + ) } diff --git a/www/docs/src/components/LearningPath/index.tsx b/www/docs/src/components/LearningPath/index.tsx index bfc272b5a7..cb69920514 100644 --- a/www/docs/src/components/LearningPath/index.tsx +++ b/www/docs/src/components/LearningPath/index.tsx @@ -18,7 +18,7 @@ const LearningPath: React.FC = ({ }) => { const path = getLearningPath(pathName) if (!path) { - throw new Error("Learning path does not exist.") + throw new Error(`Learning path ${pathName} does not exist.`) } const { startPath, path: currentPath } = useLearningPath() const notificationContext = useNotifications() @@ -43,7 +43,7 @@ const LearningPath: React.FC = ({ )} > -
+
= ({ )}
-
diff --git a/www/docs/src/components/Notification/Container/index.tsx b/www/docs/src/components/Notification/Container/index.tsx index d5b6793598..c2ec71e2fb 100644 --- a/www/docs/src/components/Notification/Container/index.tsx +++ b/www/docs/src/components/Notification/Container/index.tsx @@ -48,11 +48,11 @@ const NotificationContainer = () => { <> {renderFilteredNotifications( (notification) => notification.placement === "top", - "flex fixed flex-col gap-0.5 md:right-1 right-0 md:top-1 top-0 z-[400] md:w-auto w-full" + "flex fixed flex-col gap-0.5 right-0 top-0 z-[400] md:w-auto w-full max-h-[calc(100vh-57px)] overflow-y-auto" )} {renderFilteredNotifications( (notification) => notification.placement !== "top", - "flex flex-col gap-0.5 fixed md:right-1 right-0 md:bottom-1 bottom-0 z-[400] md:w-auto w-full" + "flex flex-col gap-0.5 fixed right-0 bottom-0 z-[400] md:w-auto w-full max-h-[calc(100vh-57px)] overflow-y-auto" )} ) diff --git a/www/docs/src/components/Notification/Item/index.tsx b/www/docs/src/components/Notification/Item/index.tsx index 0ab7610d42..5f1bd1c23d 100644 --- a/www/docs/src/components/Notification/Item/index.tsx +++ b/www/docs/src/components/Notification/Item/index.tsx @@ -36,8 +36,8 @@ const Notification = ({
{ layout: "empty", id, children: LearningStep(id), + className: "flex flex-col", }) updatePath({ notificationId: id, diff --git a/www/docs/src/utils/learning-paths.tsx b/www/docs/src/utils/learning-paths.tsx index e226fe7d02..b52abbf2c1 100644 --- a/www/docs/src/utils/learning-paths.tsx +++ b/www/docs/src/utils/learning-paths.tsx @@ -34,7 +34,7 @@ const paths: LearningPathType[] = [ type: "rating", step: { title: "Congratulations on building your store!", - description: "Please rate your experience using this learning path.", + description: "Please rate your experience using this recipe.", eventName: "rating_path_simple-quickstart", }, }, @@ -120,7 +120,7 @@ const paths: LearningPathType[] = [ type: "rating", step: { title: "Congratulations on building your marketplace!", - description: "Please rate your experience using this learning path.", + description: "Please rate your experience using this recipe.", eventName: "rating_path_marketplace", }, }, @@ -188,14 +188,277 @@ const paths: LearningPathType[] = [ type: "rating", step: { title: "Congratulations on implementing subscription-based purchases!", - description: "Please rate your experience using this learning path.", + description: "Please rate your experience using this recipe.", eventName: "rating_path_subscriptions", }, }, }, + { + name: "entity-and-api", + label: "Create Entity and Expose it with Endpoints", + description: + "Learn how to create a new table in your database, then create endpoints to expose and manipulate its data.", + steps: [ + { + title: "Create entity", + path: "/development/entities/create", + description: "Create your entity, its migration, and repository.", + }, + { + title: "Create service", + path: "/development/services/create-service", + description: + "A service is a class that defines helper methods for your entity. The service will be used by the endpoints to access or modify the entity's data.", + }, + { + title: "Create endpoints", + path: "/development/endpoints/create", + }, + ], + finish: { + type: "rating", + step: { + title: "Congratulations on creating your entity and endpoints!", + description: "Please rate your experience using this recipe.", + eventName: "rating_path_entity-and-api", + }, + }, + }, + { + name: "storefront", + label: "Create a Custom Storefront", + description: + "Learn how to create a custom storefront with your preferred language or framework.", + steps: [ + { + title: "Choose your client", + path: "/medusa-react/overview", + descriptionJSX: ( + <> + As your storefront connect to the Medusa backend, you need a way to + interact with the backend's REST APIs. There are three ways to + do so, based on your type of project: +
    +
  • + Medusa React: Can be + used in any React-based project. For example, in a Next.js + storefront. +
    • +
  • + Medusa JS Client: Can be + used in any JavaScript and NPM based project. For example, in a + Nuxt storefront. +
    • +
  • + + Store REST APIs + + : You can send requests directly to the API endpoints without + using Medusa's clients. +
    • +
+ + ), + }, + { + title: "Set CORS configurations in Backend", + path: "/development/backend/configurations#admin_cors-and-store_cors", + description: + "To ensure your storefront can connect to the backend, make sure to configure the backend's CORS configuration based on your storefront's local or remote URL.", + }, + { + title: "Create a Publishable API Key", + path: "/user-guide/settings/publishable-api-keys", + descriptionJSX: ( + <> + A publishable API key allows you to associate a key with a sales + channel. Then, you can include that key in the headers of all your + requests. +
+ You can create the publishable API key from the dashboard. + Alternatively, you can create it using the{" "} + + Admin APIs + + + ), + }, + { + title: "Use Publishable API Key", + path: "/development/publishable-api-keys/storefront/use-in-requests", + description: + "After creating the publishable API key and associating it with sales channels, you can pass it in the header of your requests to Store API endpoints.", + }, + { + title: "Add Region Selection", + path: "/modules/regions-and-currencies/storefront/use-regions", + description: + "In your storefront, you can allow your customers to view available regions and select their current region. This can affect the prices, discounts, and shipping and payment providers available to the customer.", + }, + { + title: "Display Products", + path: "/modules/products/storefront/show-products", + description: "Display products to your customers in the storefront.", + }, + { + title: "Implement Cart Functionalities", + path: "/modules/carts-and-checkout/storefront/implement-cart", + description: + "Allow your customers to add items to their cart, update them, and more in preparation for checkout.", + }, + { + title: "Implement Checkout Flow", + path: "/modules/carts-and-checkout/storefront/implement-checkout-flow", + description: + "Implement the checkout flow that allows customers to handle shipping and payment, then place their orders.", + }, + { + title: "Implement Customer Profiles", + path: "/modules/customers/storefront/implement-customer-profiles", + description: + "Allow customers to register, login, edit their profile information, and more.", + }, + { + title: "More Commerce Functionalities", + path: "/modules/overview", + descriptionJSX: ( + <> + This recipe guided you to create a storefront with basic + functionalities. You can add more functionalities to your storefront + based on your use case. +
    +
  • + The Commerce Modules{" "} + documentation holds various storefront-related how-to guides to + help you implement different features. +
    • +
  • + You can also checkout the{" "} + + Store REST APIs + {" "} + for a full list of available REST APIs. +
    • +
+ + ), + }, + ], + finish: { + type: "rating", + step: { + title: "Congratulations on creating your storefront!", + description: "Please rate your experience using this recipe.", + eventName: "rating_path_storefront", + }, + }, + }, + { + name: "plugin", + label: "Create a Plugin", + description: + "Learn how to create a plugin that can be re-used across Medusa backends.", + steps: [ + { + title: "Setup plugin project", + path: "/development/backend/install", + description: + "A plugin is initially a Medusa backend with customizations. If you don't have a project ready, you can create one using Medusa's CLI tool.", + }, + { + title: "Implement Customizations", + path: "/development/entities/create", + descriptionJSX: ( + <> + Your plugin can hold backend and admin customizations. Those + include: +
    +
  • + Create Entity +
    • +
  • + + Create Service + +
    • +
  • + + Create an Endpoint + +
    • +
  • + + Create Subscriber + +
    • +
  • + Create Admin Widgets +
    • +
  • + Create Admin Routes +
    • +
  • + + Create Admin Setting Pages + +
    • +
  • + + Create Search Service + +
    • +
  • + + Create File Service + +
    • +
  • + + Create Notification Service + +
    • +
+ If you've already made your custom development, you can skip to + the next step. + + ), + }, + { + title: "Change your package.json", + path: "/development/plugins/create#changes-to-packagejson", + descriptionJSX: ( + <> + Once you're done making your customizations and you're + ready to publish your plugin, make changes to your{" "} + package.json in preparation for publishing. + + ), + }, + { + title: "Optionally test locally", + path: "/development/plugins/create#test-your-plugin", + description: + "If necessary, you can test your plugin in a separate local Medusa backend. It's recommended, however, to do your plugin testing within the plugin project.", + }, + { + title: "Publish plugin", + path: "/development/plugins/publish", + description: "Publish your plugin on NPM.", + }, + ], + finish: { + type: "rating", + step: { + title: "Congratulations on creating your plugin!", + description: "Please rate your experience using this recipe.", + eventName: "rating_path_plugin", + }, + }, + }, ] -export const getLearningPaths = () => paths +// get a shallow copy +export const getLearningPaths = () => [...paths] export const getLearningPath = ( pathName: string