diff --git a/www/apps/book/app/learn/introduction/build-with-llms-ai/page.mdx b/www/apps/book/app/learn/introduction/build-with-llms-ai/page.mdx new file mode 100644 index 0000000000..40e687a983 --- /dev/null +++ b/www/apps/book/app/learn/introduction/build-with-llms-ai/page.mdx @@ -0,0 +1,66 @@ +import { InlineIcon } from "docs-ui" +import { AiAssistent, AiAssistentLuminosity } from "@medusajs/icons" + +export const metadata = { + title: `${pageNumber} Build with AI Assistants and LLMs`, +} + +# {metadata.title} + +In this chapter, you'll learn how you can use AI assistants and LLMs effectively in your Medusa development. + +## AI Assistant in Documentation + +The Medusa documentation is equipped with an AI Assistant that can answer your questions and help you build customizations with Medusa. + +### Open the AI Assistant + +To open the AI Assistant, either: + +- Use the keyboard shortcut `Ctrl + I` for Windows/Linux, or `Cmd + I` for macOS. +- Click the icon in the top right corner of the documentation. + +You can then ask the AI Assistant any questions about Medusa, such as: + +- What is a workflow? +- How to create a product review module? +- How to update Medusa? +- How to fix this error? + +The AI Assistant will provide you with relevant documentation links, code snippets, and explanations to help you with your development. + +### Ask About Code Snippets + +While browsing the documentation, you'll find a icon in the header of code snippets. You can click this icon to ask the AI Assistant about the code snippet. + +The AI Assistant will analyze the code and provide explanations, usage examples, and any additional information you need to understand how the code works. + +### Ask About Documentation Pages + +If you need more help understanding a specific documentation page, you can click the "Explain with AI Assistant" link in the page's right sidebar. This will open the AI Assistant and provide context about the current page, allowing you to ask questions related to the content. + +### Formatting and Code Blocks + +In your questions to the AI Assistant, you can format code blocks by wrapping them in triple backticks (```). For example: + +~~~markdown +``` +console.log("Hello, World!") +``` +~~~ + +You can add new lines using the `Shift + Enter` shortcut. + +--- + +## Plain Text Documentation + +The Medusa documentation is available in plain text format, which allows LLMs and AI tools to easily parse and understand the content. + +You can access the following plain text documentation files: + +- [llms.txt](https://docs.medusajs.com/llms.txt) - Contains a short structure of links to important documentation pages. +- [llms-full.txt](https://docs.medusajs.com/llms-full.txt) - Contains the full documentation content, including all pages and sections. +- **Markdown version of any page** - You can access the Markdown version of any documentation page by appending `/index.html.md` to the page URL. For example, the plain text content of the current page is available at [https://docs.medusajs.com/learn/introduction/build-with-llms-ai/index.html.md](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/index.html.md). + +You can provide these files to your AI tools or LLM editors like [Cursor](https://docs.cursor.com/context/@-symbols/@-docs). This will help them understand the Medusa documentation and provide better assistance when building customizations or answering questions. diff --git a/www/apps/book/app/learn/page.mdx b/www/apps/book/app/learn/page.mdx index 703576f824..b6cece0e80 100644 --- a/www/apps/book/app/learn/page.mdx +++ b/www/apps/book/app/learn/page.mdx @@ -156,10 +156,6 @@ This documentation is split into the following sections: To get started, check out the [Installation chapter](./installation/page.mdx). -### Using with LLM Editors - -This documentation provides an [llms-full.txt](https://docs.medusajs.com/llms-full.txt) file to support LLM editors. To access the documentation directly from your editor and benefit from code generation, add [https://docs.medusajs.com/llms-full.txt](https://docs.medusajs.com/llms-full.txt) as a custom documentation source in your LLM editor, such as [Cursor](https://docs.cursor.com/context/@-symbols/@-docs). - --- ## Useful Links diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index e398125e8a..e522a42138 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -2,7 +2,7 @@ export const generatedEditDates = { "app/learn/fundamentals/scheduled-jobs/page.mdx": "2024-12-09T10:51:40.570Z", "app/learn/fundamentals/workflows/page.mdx": "2024-12-09T14:45:17.837Z", "app/learn/deployment/page.mdx": "2025-06-20T08:36:29.097Z", - "app/learn/page.mdx": "2025-05-01T15:30:08.238Z", + "app/learn/page.mdx": "2025-06-27T11:39:15.941Z", "app/learn/fundamentals/modules/commerce-modules/page.mdx": "2025-04-17T08:51:32.723Z", "app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2025-03-28T07:15:19.388Z", "app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z", @@ -122,5 +122,6 @@ export const generatedEditDates = { "app/learn/fundamentals/workflows/errors/page.mdx": "2025-04-25T14:26:25.000Z", "app/learn/fundamentals/api-routes/override/page.mdx": "2025-05-09T08:01:24.493Z", "app/learn/fundamentals/module-links/index/page.mdx": "2025-05-23T07:57:58.958Z", - "app/learn/fundamentals/module-links/index-module/page.mdx": "2025-06-19T16:02:05.665Z" + "app/learn/fundamentals/module-links/index-module/page.mdx": "2025-06-19T16:02:05.665Z", + "app/learn/introduction/build-with-llms-ai/page.mdx": "2025-06-27T12:07:08.147Z" } \ No newline at end of file diff --git a/www/apps/book/generated/sidebar.mjs b/www/apps/book/generated/sidebar.mjs index a776f67aa3..753fc9c7ee 100644 --- a/www/apps/book/generated/sidebar.mjs +++ b/www/apps/book/generated/sidebar.mjs @@ -38,6 +38,16 @@ export const generatedSidebars = [ "children": [], "chapterTitle": "1.3. Architecture", "number": "1.3." + }, + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "AI Assistants and LLMs", + "path": "/learn/introduction/build-with-llms-ai", + "children": [], + "chapterTitle": "1.4. AI Assistants and LLMs", + "number": "1.4." } ], "chapterTitle": "1. Getting Started", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index b5acae8ef7..67fb9d64c6 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -18737,6 +18737,67 @@ The following diagram illustrates Medusa's architecture including all its layers ![Full diagram illustrating Medusa's architecture combining all the different layers.](https://res.cloudinary.com/dza7lstvk/image/upload/v1727174897/Medusa%20Book/architectural-diagram-full.jpg) +# Build with AI Assistants and LLMs + +In this chapter, you'll learn how you can use AI assistants and LLMs effectively in your Medusa development. + +## AI Assistant in Documentation + +The Medusa documentation is equipped with an AI Assistant that can answer your questions and help you build customizations with Medusa. + +### Open the AI Assistant + +To open the AI Assistant, either: + +- Use the keyboard shortcut `Ctrl + I` for Windows/Linux, or `Cmd + I` for macOS. +- Click the icon in the top right corner of the documentation. + +You can then ask the AI Assistant any questions about Medusa, such as: + +- What is a workflow? +- How to create a product review module? +- How to update Medusa? +- How to fix this error? + +The AI Assistant will provide you with relevant documentation links, code snippets, and explanations to help you with your development. + +### Ask About Code Snippets + +While browsing the documentation, you'll find a icon in the header of code snippets. You can click this icon to ask the AI Assistant about the code snippet. + +The AI Assistant will analyze the code and provide explanations, usage examples, and any additional information you need to understand how the code works. + +### Ask About Documentation Pages + +If you need more help understanding a specific documentation page, you can click the "Explain with AI Assistant" link in the page's right sidebar. This will open the AI Assistant and provide context about the current page, allowing you to ask questions related to the content. + +### Formatting and Code Blocks + +In your questions to the AI Assistant, you can format code blocks by wrapping them in triple backticks (\`\`\`). For example: + +````markdown +``` +console.log("Hello, World!") +``` +```` + +You can add new lines using the `Shift + Enter` shortcut. + +*** + +## Plain Text Documentation + +The Medusa documentation is available in plain text format, which allows LLMs and AI tools to easily parse and understand the content. + +You can access the following plain text documentation files: + +- [llms.txt](https://docs.medusajs.com/llms.txt/index.html.md) - Contains a short structure of links to important documentation pages. +- [llms-full.txt](https://docs.medusajs.com/llms-full.txt/index.html.md) - Contains the full documentation content, including all pages and sections. +- **Markdown version of any page** - You can access the Markdown version of any documentation page by appending `/index.html.md` to the page URL. For example, the plain text content of the current page is available at [https://docs.medusajs.com/learn/introduction/build-with-llms-ai/index.html.md](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/index.html.md). + +You can provide these files to your AI tools or LLM editors like [Cursor](https://docs.cursor.com/context/@-symbols/@-docs). This will help them understand the Medusa documentation and provide better assistance when building customizations or answering questions. + + # Introduction Medusa is a digital commerce platform with a built-in Framework for customization. @@ -18791,10 +18852,6 @@ This documentation is split into the following sections: To get started, check out the [Installation chapter](https://docs.medusajs.com/learn/installation/index.html.md). -### Using with LLM Editors - -This documentation provides an [llms-full.txt](https://docs.medusajs.com/llms-full.txt/index.html.md) file to support LLM editors. To access the documentation directly from your editor and benefit from code generation, add [https://docs.medusajs.com/llms-full.txt](https://docs.medusajs.com/llms-full.txt/index.html.md) as a custom documentation source in your LLM editor, such as [Cursor](https://docs.cursor.com/context/@-symbols/@-docs). - *** ## Useful Links @@ -47121,7 +47178,7 @@ To learn more about the commerce features that Medusa provides, check out Medusa In this tutorial, you'll learn how to implement first-purchase discounts in Medusa. -When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md), which are available out-of-the-box. These features include promotion and discount management features. +When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md), which are available out-of-the-box. These features include promotion and cart management features. The first-purchase discount feature encourages customers to sign up and make their first purchase by offering them a discount. In this tutorial, you'll learn how to implement this feature in Medusa. @@ -47248,8 +47305,8 @@ export const applyFirstPurchasePromoWorkflow = createWorkflow( entity: "cart", fields: ["promotions.*", "customer.*", "customer.orders.*"], filters: { - id: input.cart_id - } + id: input.cart_id, + }, }) const { data: promotions } = useQueryGraphStep({ @@ -47262,7 +47319,7 @@ export const applyFirstPurchasePromoWorkflow = createWorkflow( when({ carts, - promotions + promotions, }, (data) => { return data.promotions.length > 0 && !data.carts[0].promotions?.some((promo) => promo?.id === data.promotions[0].id) && @@ -47273,7 +47330,7 @@ export const applyFirstPurchasePromoWorkflow = createWorkflow( updateCartPromotionsStep({ id: carts[0].id, promo_codes: [promotions[0].code!], - action: PromotionActions.ADD + action: PromotionActions.ADD, }) }) @@ -47282,8 +47339,8 @@ export const applyFirstPurchasePromoWorkflow = createWorkflow( entity: "cart", fields: ["*", "promotions.*"], filters: { - id: input.cart_id - } + id: input.cart_id, + }, }).config({ name: "retrieve-updated-cart" }) return new WorkflowResponse(updatedCarts[0]) @@ -47332,8 +47389,8 @@ export default async function cartCreatedHandler({ await applyFirstPurchasePromoWorkflow(container) .run({ input: { - cart_id: data.id - } + cart_id: data.id, + }, }) } @@ -47431,8 +47488,8 @@ updateCartPromotionsWorkflow.hooks.validate( entity: "customer", fields: ["orders.*", "has_account"], filters: { - id: cart.customer_id - } + id: cart.customer_id, + }, }) if (!customer.has_account || (customer?.orders?.length || 0) > 0) { @@ -47472,7 +47529,7 @@ In the same `src/workflows/hooks/validate-promotion.ts` file, add the following ```ts title="src/workflows/hooks/validate-promotion.ts" import { - completeCartWorkflow + completeCartWorkflow, } from "@medusajs/medusa/core-flows" ``` @@ -47502,8 +47559,8 @@ completeCartWorkflow.hooks.validate( entity: "customer", fields: ["orders.*", "has_account"], filters: { - id: cart.customer_id - } + id: cart.customer_id, + }, }) if (!customer.has_account || (customer?.orders?.length || 0) > 0) { @@ -47711,6 +47768,635 @@ If you encounter issues not covered in the troubleshooting guides: 2. Join the [Medusa Discord community](https://discord.gg/medusajs) for real-time support from community members. +# Add Gift Message to Line Items in Medusa + +In this tutorial, you will learn how to add a gift message to items in carts and orders in Medusa. + +When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md), which are available out-of-the-box. These features include cart and order management capabilities. + +You can customize the Medusa application and storefront to add a gift message to items in the cart. This feature allows customers to add a personalized message to their gifts, enhancing the shopping experience. + +## Summary + +By following this tutorial, you will learn how to: + +- Install and set up Medusa and the Next.js Starter Storefront. +- Customize the storefront to support gift messages on cart items during checkout. +- Customize the Medusa Admin to show gift items with messages in an order. + +You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer. + +[View on Github](https://github.com/medusajs/examples/tree/main/order-gift-message): Find the full code for this tutorial. + +*** + +## Step 1: Install a Medusa Application + +### Prerequisites + +- [Node.js v20+](https://nodejs.org/en/download) +- [Git CLI tool](https://git-scm.com/downloads) +- [PostgreSQL](https://www.postgresql.org/download/) + +Start by installing the Medusa application on your machine with the following command: + +```bash +npx create-medusa-app@latest +``` + +First, you'll be asked for the project's name. Then, when prompted about installing the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose "Yes." + +Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name and the Next.js Starter Storefront in a separate directory named `{project-name}-storefront`. + +The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md). Learn more in [Medusa's Architecture documentation](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md). + +Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterward, you can log in with the new user and explore the dashboard. + +Check out the [troubleshooting guides](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/troubleshooting/create-medusa-app-errors/index.html.md) for help. + +*** + +## Step 2: Add Gift Inputs to Cart Item + +In this step, you'll customize the Next.js Starter Storefront to allow customers to specify that an item is a gift and add a gift message to it. + +You'll store the gift option and message in the cart item's `metadata` property, which is a key-value `jsonb` object that can hold any additional information about the item. When the customer places the order, the `metadata` is copied to the `metadata` of the order's line items. + +So, you only need to customize the storefront to add the gift message input and update the cart item metadata. + +### a. Changes to Update Item Function + +The Next.js Starter Storefront has an `updateLineItem` function that sends a request to the Medusa server to update the cart item. However, it doesn't support updating the `metadata` property. + +So, in `src/lib/data/cart.ts`, find the `updateLineItem` function and add a `metadata` property to its object parameter: + +```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue" highlights={[["4"], ["8"]]} +export async function updateLineItem({ + lineId, + quantity, + metadata, +}: { + lineId: string + quantity: number + metadata?: Record +}) { + // ... +} +``` + +Next, change the usage of `await sdk.store.cart.updateLineItem` in the function to pass the `metadata` property: + +```ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue" +const updateData: any = { quantity } +if (metadata) { + updateData.metadata = metadata +} + +await sdk.store.cart + .updateLineItem(cartId, lineId, updateData, {}, headers) +// ... +``` + +You pass the `metadata` property to the Medusa server, which will update the cart item with the new metadata. + +### b. Add Gift Inputs + +Next, you'll modify the cart item component that's shown in the cart and checkout pages to show two inputs: one to specify that the item is a gift and another to add a gift message. + +In `src/modules/cart/components/item/index.tsx`, add the following imports at the top of the file: + +```tsx title="src/modules/cart/components/item/index.tsx" badgeLabel="Storefront" badgeColor="blue" +import { Checkbox, Textarea, Button, Label } from "@medusajs/ui" +``` + +You import components from the [Medusa UI library](https://docs.medusajs.com/ui/index.html.md) that will be useful for the gift inputs. + +Next, in the `Item` component, add the following variables before the `changeQuantity` function: + +```tsx title="src/modules/cart/components/item/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={giftVarsHighlights} +const [giftUpdating, setGiftUpdating] = useState(false) +const [newGiftMessage, setNewGiftMessage] = useState( + item.metadata?.gift_message as string || "" +) +const [isEditingGiftMessage, setIsEditingGiftMessage] = useState(false) + +const isGift = item.metadata?.is_gift === "true" +const giftMessage = item.metadata?.gift_message as string +``` + +You define the following variables: + +- `giftUpdating`: A state variable to track whether the gift message is being updated. This will be useful to handle loading and disabled states. +- `newGiftMessage`: A state variable to hold the new gift message input value. +- `isEditingGiftMessage`: A state variable to track whether the gift message input is being edited. This will be useful to show or hide the input field. +- `isGift`: A boolean indicating whether the item is a gift based on the `metadata.is_gift` property. +- `giftMessage`: The current gift message from the item's `metadata.gift_message` property. + +Next, add the following functions before the `return` statement to handle updates to the gift inputs: + +```tsx title="src/modules/cart/components/item/index.tsx" badgeLabel="Storefront" badgeColor="blue" highlights={giftFunctionsHighlights} +const handleGiftToggle = async (checked: boolean) => { + setGiftUpdating(true) + + try { + const newMetadata = { + is_gift: checked.toString(), + gift_message: checked ? newGiftMessage : "", + } + + await updateLineItem({ + lineId: item.id, + quantity: item.quantity, + metadata: newMetadata, + }) + } catch (error) { + console.error("Error updating gift status:", error) + } finally { + setGiftUpdating(false) + } +} + +const handleSaveGiftMessage = async () => { + setGiftUpdating(true) + + try { + const newMetadata = { + is_gift: "true", + gift_message: newGiftMessage, + } + + await updateLineItem({ + lineId: item.id, + quantity: item.quantity, + metadata: newMetadata, + }) + setIsEditingGiftMessage(false) + } catch (error) { + console.error("Error updating gift message:", error) + } finally { + setGiftUpdating(false) + } +} + +const handleStartEdit = () => { + setIsEditingGiftMessage(true) +} + +const handleCancelEdit = () => { + setNewGiftMessage(giftMessage || "") + setIsEditingGiftMessage(false) +} +``` + +You define the following functions: + +- `handleGiftToggle`: Used when the gift checkbox is toggled. It updates the cart item's metadata to set the `is_gift` and `gift_message` properties based on the checkbox state. +- `handleSaveGiftMessage`: Used to save the gift message when the customer clicks the "Save" button. It updates the cart item's metadata with the new gift message. +- `handleStartEdit`: Used to start editing the gift message input by setting the `isEditingGiftMessage` state to `true`. +- `handleCancelEdit`: Used to cancel the gift message editing and reset the input value to the current gift message. + +Finally, you'll change the `return` statement to include the gift inputs. Replace the existing return statement with the following: + +```tsx title="src/modules/cart/components/item/index.tsx" badgeLabel="Storefront" badgeColor="blue" +return ( +
+
+ {/* Product Image */} +
+ + + +
+ + {/* Product Details */} +
+
+
+ + {item.product_title} + + +
+
+ + {/* Gift Options */} +
+
+ + +
+ + {isGift && ( +
+ {isEditingGiftMessage ? ( +
+
+ + Gift Message: + + (optional) +
+