- Product Widget
-
-
-
- Product Widget {data.title}
-
-
-
+ Product Widget
+
+
+
+ Product Widget {data.title}
+
+
+
+
+
+
+```
+
+This template will show each item's image, title, quantity, and price in the cart. It will also show a button to return to the cart and checkout.
+
+You can replace `https://yourstore.com` with your storefront's URL. You'll later implement the `/cart/recover/:cart_id` route in the storefront to recover the cart.
+
+Once you are done, copy the template ID from SendGrid and set it as an environment variable in your Medusa project:
+
+```plain
+ABANDONED_CART_TEMPLATE_ID=your-sendgrid-template-id
+```
+
+***
+
+## Step 4: Schedule Cart Abandonment Notifications
+
+The next step is to automate sending the abandoned cart notifications. You need a task that runs once a day to find the carts that have been abandoned for a certain period and send the notifications to the customers.
+
+To run a task at a scheduled interval, you can use a [scheduled job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md). A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
+
+You can create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. So, to create the scheduled job that sends the abandoned cart notifications, create the file `src/jobs/send-abandoned-cart-notification.ts` with the following content:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import {
+ sendAbandonedCartsWorkflow,
+ SendAbandonedCartsWorkflowInput,
+} from "../workflows/send-abandoned-carts"
+
+export default async function abandonedCartJob(
+ container: MedusaContainer
+) {
+ const logger = container.resolve("logger")
+ const query = container.resolve("query")
+
+ const oneDayAgo = new Date()
+ oneDayAgo.setDate(oneDayAgo.getDate() - 1)
+ const limit = 100
+ const offset = 0
+ const totalCount = 0
+ const abandonedCartsCount = 0
+
+ do {
+ // TODO retrieve paginated abandoned carts
+ } while (offset < totalCount)
+
+ logger.info(`Sent ${abandonedCartsCount} abandoned cart notifications`)
+}
+
+export const config = {
+ name: "abandoned-cart-notification",
+ schedule: "0 0 * * *", // Run at midnight every day
+}
+```
+
+In a scheduled job's file, you must export:
+
+1. An asynchronous function that holds the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
+2. A `config` object that specifies the job's name and schedule. The schedule is a [cron expression](https://crontab.guru/) that defines the interval at which the job runs.
+
+In the scheduled job function, so far you resolve the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) to log messages, and [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve data across modules.
+
+You also define a `oneDayAgo` date, which is the date that you will use as the condition of an abandoned cart. In addition, you define variables to paginate the carts.
+
+Next, you will retrieve the abandoned carts using Query. Replace the `TODO` with the following:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+const {
+ data: abandonedCarts,
+ metadata,
+} = await query.graph({
+ entity: "cart",
+ fields: [
+ "id",
+ "email",
+ "items.*",
+ "metadata",
+ "customer.*",
+ ],
+ filters: {
+ updated_at: {
+ $lt: oneDayAgo,
+ },
+ // @ts-ignore
+ email: {
+ $ne: null,
+ },
+ // @ts-ignore
+ completed_at: null,
+ },
+ pagination: {
+ skip: offset,
+ take: limit,
+ },
+})
+
+totalCount = metadata?.count ?? 0
+const cartsWithItems = abandonedCarts.filter((cart) =>
+ cart.items?.length > 0 && !cart.metadata?.abandoned_notification
+)
+
+try {
+ await sendAbandonedCartsWorkflow(container).run({
+ input: {
+ carts: cartsWithItems,
+ } as unknown as SendAbandonedCartsWorkflowInput,
+ })
+ abandonedCartsCount += cartsWithItems.length
+
+} catch (error) {
+ logger.error(
+ `Failed to send abandoned cart notification: ${error.message}`
+ )
+}
+
+offset += limit
+```
+
+In the do-while loop, you use Query to retrieve carts matching the following criteria:
+
+- The cart was last updated more than a day ago.
+- The cart has an email address.
+- The cart has not been completed.
+
+You also filter the retrieved carts to only include carts with items and customers that have not received an abandoned cart notification.
+
+Finally, you execute the `sendAbandonedCartsWorkflow` passing it the abandoned carts as an input. You will execute the workflow for each paginated batch of carts.
+
+### Test it Out
+
+To test out the scheduled job and workflow, it is recommended to change the `oneDayAgo` date to a minute before now for easy testing:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+oneDayAgo.setMinutes(oneDayAgo.getMinutes() - 1) // For testing
+```
+
+And to change the job's schedule in `config` to run every minute:
+
+```ts title="src/jobs/send-abandoned-cart-notification.ts"
+export const config = {
+ // ...
+ schedule: "* * * * *", // Run every minute for testing
+}
+```
+
+Finally, start the Medusa application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+And in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md)'s directory (that you installed in the first step), start the storefront with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+Open the storefront at `localhost:8000`. You can either:
+
+- Create an account and add items to the cart, then leave the cart for a minute.
+- Add an item to the cart as a guest. Then, start the checkout process, but only enter the shipping and email addresses, and leave the cart for a minute.
+
+Afterwards, wait for the job to execute. Once it is executed, you will see the following message in the terminal:
+
+```bash
+info: Sent 1 abandoned cart notifications
+```
+
+Once you're done testing, make sure to revert the changes to the `oneDayAgo` date and the job's schedule.
+
+***
+
+## Step 5: Recover Cart in Storefront
+
+In the storefront, you need to add a route that recovers the cart when the customer clicks on the link in the email. The route should receive the cart ID, set the cart ID in the cookie, and redirect the customer to the cart page.
+
+To implement the route, in the Next.js Starter Storefront create the file `src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx` with the following content:
+
+```tsx title="src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx" badgeLabel="Storefront" badgeColor="blue"
+import { NextRequest } from "next/server"
+import { retrieveCart } from "../../../../../../lib/data/cart"
+import { setCartId } from "../../../../../../lib/data/cookies"
+import { notFound, redirect } from "next/navigation"
+type Params = Promise<{
+ id: string
+}>
+
+export async function GET(req: NextRequest, { params }: { params: Params }) {
+ const { id } = await params
+ const cart = await retrieveCart(id)
+
+ if (!cart) {
+ return notFound()
+ }
+
+ setCartId(id)
+
+ const countryCode = cart.shipping_address?.country_code ||
+ cart.region?.countries?.[0]?.iso_2
+
+ redirect(
+ `/${countryCode ? `${countryCode}/` : ""}cart`
+ )
+}
+```
+
+You add a `GET` route handler that receives the cart ID as a path parameter. In the route handler, you:
+
+- Try to retrieve the cart from the Medusa application. The `retrieveCart` function is already available in the Next.js storefront. If the cart is not found, you return a 404 response.
+- Set the cart ID in a cookie using the `setCartId` function. This is also a function that is already available in the storefront.
+- Redirect the customer to the cart page. You set the country code in the URL based on the cart's shipping address or region.
+
+### Test it Out
+
+To test it out, start the Medusa application:
+
+```bash npm2yarn
+npm run dev
+```
+
+And in the Next.js Starter Storefront's directory, start the storefront:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, either open the link in an abandoned cart email or navigate to `localhost:8000/cart/recover/:cart_id` in your browser. You will be redirected to the cart page with the recovered cart.
+
+
+
+***
+
+## Next Steps
+
+You have now implemented the logic to send abandoned cart notifications in Medusa. You can implement other customizations with Medusa, such as:
+
+- [Implement Product Reviews](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/how-to-tutorials/tutorials/product-reviews/index.html.md).
+- [Implement Wishlist](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/plugins/guides/wishlist/index.html.md).
+- [Allow Custom-Item Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/examples/guides/custom-item-price/index.html.md).
+
+If you are new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you will get a more in-depth learning of all the concepts you have used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
+
+
# Implement Loyalty Points System in Medusa
In this tutorial, you'll learn how to implement a loyalty points system in Medusa.
+Medusa Cloud provides a beta Store Credits feature that facilitates building a loyalty point system. [Get in touch](https://medusajs.com/contact) for early access.
+
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 management capabilities related to carts, orders, promotions, and more.
A loyalty point system allows customers to earn points for purchases, which can be redeemed for discounts or rewards. In this tutorial, you'll learn how to customize the Medusa application to implement a loyalty points system.
@@ -40880,637 +42272,6 @@ If you're new to Medusa, check out the [main documentation](https://docs.medusaj
To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-# Send Abandoned Cart Notifications in Medusa
-
-In this tutorial, you will learn how to send notifications to customers who have abandoned their carts.
-
-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-management capabilities.
-
-Medusa's [Notification Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/architectural-modules/notification/index.html.md) allows you to send notifications to users or customers, such as password reset emails, order confirmation SMS, or other types of notifications.
-
-In this tutorial, you will use the Notification Module to send an email to customers who have abandoned their carts. The email will contain a link to recover the customer's cart, encouraging them to complete their purchase. You will use SendGrid to send the emails, but you can also use other email providers.
-
-## Summary
-
-By following this tutorial, you will:
-
-- Install and set up Medusa.
-- Create the logic to send an email to customers who have abandoned their carts.
-- Run the above logic once a day.
-- Add a route to the storefront to recover the cart.
-
-
-
-[View on Github](https://github.com/medusajs/examples/tree/main/abandoned-cart): 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
-```
-
-You will first be asked for the project's name. Then, when asked whether you want to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md), choose "Yes."
-
-Afterwards, 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 with the `{project-name}-storefront` name.
-
-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. Afterwards, 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: Set up SendGrid
-
-### Prerequisites
-
-- [SendGrid account](https://sendgrid.com)
-- [Verified Sender Identity](https://mc.sendgrid.com/senders)
-- [SendGrid API Key](https://app.sendgrid.com/settings/api_keys)
-
-Medusa's Notification Module provides the general functionality to send notifications, but the sending logic is implemented in a module provider. This allows you to integrate the email provider of your choice.
-
-To send the cart-abandonment emails, you will use SendGrid. Medusa provides a [SendGrid Notification Module Provider](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/architectural-modules/notification/sendgrid/index.html.md) that you can use to send emails.
-
-Alternatively, you can use [other Notification Module Providers](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/architectural-modules/notification#what-is-a-notification-module-provider/index.html.md) or [create a custom provider](https://docs.medusajs.com/references/notification-provider-module/index.html.md).
-
-To set up SendGrid, add the SendGrid Notification Module Provider to `medusa-config.ts`:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- modules: [
- {
- resolve: "@medusajs/medusa/notification",
- options: {
- providers: [
- {
- resolve: "@medusajs/medusa/notification-sendgrid",
- id: "sendgrid",
- options: {
- channels: ["email"],
- api_key: process.env.SENDGRID_API_KEY,
- from: process.env.SENDGRID_FROM,
- },
- },
- ],
- },
- },
- ],
-})
-```
-
-In the `modules` configuration, you pass the Notification Provider and add SendGrid as a provider. You also pass to the SendGrid Module Provider the following options:
-
-- `channels`: The channels that the provider supports. In this case, it is only email.
-- `api_key`: Your SendGrid API key.
-- `from`: The email address that the emails will be sent from.
-
-Then, set the SendGrid API key and "from" email as environment variables, such as in the `.env` file at the root of your project:
-
-```plain
-SENDGRID_API_KEY=your-sendgrid-api-key
-SENDGRID_FROM=test@gmail.com
-```
-
-You can now use SendGrid to send emails in Medusa.
-
-***
-
-## Step 3: Send Abandoned Cart Notification Flow
-
-You will now implement the sending logic for the abandoned cart notifications.
-
-To build custom commerce features in Medusa, you create a [workflow](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md). A workflow is a series of queries and actions, called steps, that complete a task. You construct a workflow like you construct a function, but it is a special function that allows you to track its executions' progress, define roll-back logic, and configure other advanced features. Then, you execute the workflow from other customizations, such as in a scheduled job.
-
-In this step, you will create the workflow that sends the abandoned cart notifications. Later, you will learn how to execute it once a day.
-
-The workflow will receive the list of abandoned carts as an input. The workflow has the following steps:
-
-- [sendAbandonedNotificationsStep](#sendAbandonedNotificationsStep): Send the abandoned cart notifications.
-- [updateCartsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateCartsStep/index.html.md): Update the cart to store the last notification date.
-
-Medusa provides the second step in its `@medusajs/medusa/core-flows` package. So, you only need to implement the first one.
-
-### sendAbandonedNotificationsStep
-
-The first step of the workflow sends a notification to the owners of the abandoned carts that are passed as an input.
-
-To implement the step, create the file `src/workflows/steps/send-abandoned-notifications.ts` with the following content:
-
-```ts title="src/workflows/steps/send-abandoned-notifications.ts"
-import {
- createStep,
- StepResponse,
-} from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-import { CartDTO, CustomerDTO } from "@medusajs/framework/types"
-
-type SendAbandonedNotificationsStepInput = {
- carts: (CartDTO & {
- customer: CustomerDTO
- })[]
-}
-
-export const sendAbandonedNotificationsStep = createStep(
- "send-abandoned-notifications",
- async (input: SendAbandonedNotificationsStepInput, { container }) => {
- const notificationModuleService = container.resolve(
- Modules.NOTIFICATION
- )
-
- const notificationData = input.carts.map((cart) => ({
- to: cart.email!,
- channel: "email",
- template: process.env.ABANDONED_CART_TEMPLATE_ID || "",
- data: {
- customer: {
- first_name: cart.customer?.first_name || cart.shipping_address?.first_name,
- last_name: cart.customer?.last_name || cart.shipping_address?.last_name,
- },
- cart_id: cart.id,
- items: cart.items?.map((item) => ({
- product_title: item.title,
- quantity: item.quantity,
- unit_price: item.unit_price,
- thumbnail: item.thumbnail,
- })),
- },
- }))
-
- const notifications = await notificationModuleService.createNotifications(
- notificationData
- )
-
- return new StepResponse({
- notifications,
- })
- }
-)
-```
-
-You create a step with `createStep` from the Workflows SDK. It accepts two parameters:
-
-1. The step's unique name, which is `create-review`.
-2. An async function that receives two parameters:
- - The step's input, which is in this case an object with the review's properties.
- - An object that has properties including the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md), which is a registry of framework and commerce tools that you can access in the step.
-
-In the step function, you first resolve the Notification Module's service, which has methods to manage notifications. Then, you prepare the data of each notification, and create the notifications with the `createNotifications` method.
-
-Notice that each notification is an object with the following properties:
-
-- `to`: The email address of the customer.
-- `channel`: The channel that the notification will be sent through. The Notification Module uses the provider registered for the channel.
-- `template`: The ID or name of the email template in the third-party provider. Make sure to set it as an environment variable once you have it.
-- `data`: The data to pass to the template to render the email's dynamic content.
-
-Based on the dynamic template you create in SendGrid or another provider, you can pass different data in the `data` object.
-
-A step function must return a `StepResponse` instance. The `StepResponse` constructor accepts the step's output as a parameter, which is the created notifications.
-
-### Create Workflow
-
-You can now create the workflow that uses the step you just created to send the abandoned cart notifications.
-
-Create the file `src/workflows/send-abandoned-carts.ts` with the following content:
-
-```ts title="src/workflows/send-abandoned-carts.ts"
-import {
- createWorkflow,
- WorkflowResponse,
- transform,
-} from "@medusajs/framework/workflows-sdk"
-import {
- sendAbandonedNotificationsStep,
-} from "./steps/send-abandoned-notifications"
-import { updateCartsStep } from "@medusajs/medusa/core-flows"
-import { CartDTO } from "@medusajs/framework/types"
-import { CustomerDTO } from "@medusajs/framework/types"
-
-export type SendAbandonedCartsWorkflowInput = {
- carts: (CartDTO & {
- customer: CustomerDTO
- })[]
-}
-
-export const sendAbandonedCartsWorkflow = createWorkflow(
- "send-abandoned-carts",
- function (input: SendAbandonedCartsWorkflowInput) {
- sendAbandonedNotificationsStep(input)
-
- const updateCartsData = transform(
- input,
- (data) => {
- return data.carts.map((cart) => ({
- id: cart.id,
- metadata: {
- ...cart.metadata,
- abandoned_notification: new Date().toISOString(),
- },
- }))
- }
- )
-
- const updatedCarts = updateCartsStep(updateCartsData)
-
- return new WorkflowResponse(updatedCarts)
- }
-)
-```
-
-You create a workflow using `createWorkflow` from the Workflows SDK. It accepts the workflow's unique name as a first parameter.
-
-It accepts as a second parameter a constructor function, which is the workflow's implementation. The function can accept input, which in this case is an arra of carts.
-
-In the workflow's constructor function, you:
-
-- Use the `sendAbandonedNotificationsStep` to send the notifications to the carts' customers.
-- Use the `updateCartsStep` from Medusa's core flows to update the carts' metadata with the last notification date.
-
-Notice that you use the `transform` function to prepare the `updateCartsStep`'s input. Medusa does not support direct data manipulation in a workflow's constructor function. You can learn more about it in the [Data Manipulation in Workflows documentation](https://docs.medusajs.com/docs/learn/fundamentals/workflows/variable-manipulation/index.html.md).
-
-Your workflow is now ready for use. You will learn how to execute it in the next section.
-
-### Setup Email Template
-
-Before you can test the workflow, you need to set up an email template in SendGrid. The template should contain the dynamic content that you pass in the workflow's step.
-
-To create an email template in SendGrid:
-
-- Go to [Dynamic Templates](https://mc.sendgrid.com/dynamic-templates) in the SendGrid dashboard.
-- Click on the "Create Dynamic Template" button.
-
-
-
-- In the side window that opens, enter a name for the template, then click on the Create button.
-- The template will be added to the middle of the page. When you click on it, a new section will show with an "Add Version" button. Click on it.
-
-
-
-In the form that opens, you can either choose to start with a blank template or from an existing design. You can then use the drag-and-drop or code editor to design the email template.
-
-You can also use the following template as an example:
-
-```html title="Abandoned Cart Email Template"
-
-
-
-
-
- Hi {{customer.first_name}}, your cart is waiting! 🛍️
+
+
+ {{#each items}}
+
+ 
+
+ {{/each}}
+
+ Return to Cart & Checkout
+
+
+ {{product_title}}
+
+ {{subtitle}}
+Quantity: {{quantity}}
+Price: $ {{unit_price}}
+
-
-
-
-```
-
-This template will show each item's image, title, quantity, and price in the cart. It will also show a button to return to the cart and checkout.
-
-You can replace `https://yourstore.com` with your storefront's URL. You'll later implement the `/cart/recover/:cart_id` route in the storefront to recover the cart.
-
-Once you are done, copy the template ID from SendGrid and set it as an environment variable in your Medusa project:
-
-```plain
-ABANDONED_CART_TEMPLATE_ID=your-sendgrid-template-id
-```
-
-***
-
-## Step 4: Schedule Cart Abandonment Notifications
-
-The next step is to automate sending the abandoned cart notifications. You need a task that runs once a day to find the carts that have been abandoned for a certain period and send the notifications to the customers.
-
-To run a task at a scheduled interval, you can use a [scheduled job](https://docs.medusajs.com/docs/learn/fundamentals/scheduled-jobs/index.html.md). A scheduled job is an asynchronous function that the Medusa application runs at the interval you specify during the Medusa application's runtime.
-
-You can create a scheduled job in a TypeScript or JavaScript file under the `src/jobs` directory. So, to create the scheduled job that sends the abandoned cart notifications, create the file `src/jobs/send-abandoned-cart-notification.ts` with the following content:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-import { MedusaContainer } from "@medusajs/framework/types"
-import {
- sendAbandonedCartsWorkflow,
- SendAbandonedCartsWorkflowInput,
-} from "../workflows/send-abandoned-carts"
-
-export default async function abandonedCartJob(
- container: MedusaContainer
-) {
- const logger = container.resolve("logger")
- const query = container.resolve("query")
-
- const oneDayAgo = new Date()
- oneDayAgo.setDate(oneDayAgo.getDate() - 1)
- const limit = 100
- const offset = 0
- const totalCount = 0
- const abandonedCartsCount = 0
-
- do {
- // TODO retrieve paginated abandoned carts
- } while (offset < totalCount)
-
- logger.info(`Sent ${abandonedCartsCount} abandoned cart notifications`)
-}
-
-export const config = {
- name: "abandoned-cart-notification",
- schedule: "0 0 * * *", // Run at midnight every day
-}
-```
-
-In a scheduled job's file, you must export:
-
-1. An asynchronous function that holds the job's logic. The function receives the [Medusa container](https://docs.medusajs.com/docs/learn/fundamentals/medusa-container/index.html.md) as a parameter.
-2. A `config` object that specifies the job's name and schedule. The schedule is a [cron expression](https://crontab.guru/) that defines the interval at which the job runs.
-
-In the scheduled job function, so far you resolve the [Logger](https://docs.medusajs.com/docs/learn/debugging-and-testing/logging/index.html.md) to log messages, and [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) to retrieve data across modules.
-
-You also define a `oneDayAgo` date, which is the date that you will use as the condition of an abandoned cart. In addition, you define variables to paginate the carts.
-
-Next, you will retrieve the abandoned carts using Query. Replace the `TODO` with the following:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-const {
- data: abandonedCarts,
- metadata,
-} = await query.graph({
- entity: "cart",
- fields: [
- "id",
- "email",
- "items.*",
- "metadata",
- "customer.*",
- ],
- filters: {
- updated_at: {
- $lt: oneDayAgo,
- },
- // @ts-ignore
- email: {
- $ne: null,
- },
- // @ts-ignore
- completed_at: null,
- },
- pagination: {
- skip: offset,
- take: limit,
- },
-})
-
-totalCount = metadata?.count ?? 0
-const cartsWithItems = abandonedCarts.filter((cart) =>
- cart.items?.length > 0 && !cart.metadata?.abandoned_notification
-)
-
-try {
- await sendAbandonedCartsWorkflow(container).run({
- input: {
- carts: cartsWithItems,
- } as unknown as SendAbandonedCartsWorkflowInput,
- })
- abandonedCartsCount += cartsWithItems.length
-
-} catch (error) {
- logger.error(
- `Failed to send abandoned cart notification: ${error.message}`
- )
-}
-
-offset += limit
-```
-
-In the do-while loop, you use Query to retrieve carts matching the following criteria:
-
-- The cart was last updated more than a day ago.
-- The cart has an email address.
-- The cart has not been completed.
-
-You also filter the retrieved carts to only include carts with items and customers that have not received an abandoned cart notification.
-
-Finally, you execute the `sendAbandonedCartsWorkflow` passing it the abandoned carts as an input. You will execute the workflow for each paginated batch of carts.
-
-### Test it Out
-
-To test out the scheduled job and workflow, it is recommended to change the `oneDayAgo` date to a minute before now for easy testing:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-oneDayAgo.setMinutes(oneDayAgo.getMinutes() - 1) // For testing
-```
-
-And to change the job's schedule in `config` to run every minute:
-
-```ts title="src/jobs/send-abandoned-cart-notification.ts"
-export const config = {
- // ...
- schedule: "* * * * *", // Run every minute for testing
-}
-```
-
-Finally, start the Medusa application with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-And in the [Next.js Starter Storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md)'s directory (that you installed in the first step), start the storefront with the following command:
-
-```bash npm2yarn
-npm run dev
-```
-
-Open the storefront at `localhost:8000`. You can either:
-
-- Create an account and add items to the cart, then leave the cart for a minute.
-- Add an item to the cart as a guest. Then, start the checkout process, but only enter the shipping and email addresses, and leave the cart for a minute.
-
-Afterwards, wait for the job to execute. Once it is executed, you will see the following message in the terminal:
-
-```bash
-info: Sent 1 abandoned cart notifications
-```
-
-Once you're done testing, make sure to revert the changes to the `oneDayAgo` date and the job's schedule.
-
-***
-
-## Step 5: Recover Cart in Storefront
-
-In the storefront, you need to add a route that recovers the cart when the customer clicks on the link in the email. The route should receive the cart ID, set the cart ID in the cookie, and redirect the customer to the cart page.
-
-To implement the route, in the Next.js Starter Storefront create the file `src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx` with the following content:
-
-```tsx title="src/app/[countryCode]/(main)/cart/recover/[id]/route.tsx" badgeLabel="Storefront" badgeColor="blue"
-import { NextRequest } from "next/server"
-import { retrieveCart } from "../../../../../../lib/data/cart"
-import { setCartId } from "../../../../../../lib/data/cookies"
-import { notFound, redirect } from "next/navigation"
-type Params = Promise<{
- id: string
-}>
-
-export async function GET(req: NextRequest, { params }: { params: Params }) {
- const { id } = await params
- const cart = await retrieveCart(id)
-
- if (!cart) {
- return notFound()
- }
-
- setCartId(id)
-
- const countryCode = cart.shipping_address?.country_code ||
- cart.region?.countries?.[0]?.iso_2
-
- redirect(
- `/${countryCode ? `${countryCode}/` : ""}cart`
- )
-}
-```
-
-You add a `GET` route handler that receives the cart ID as a path parameter. In the route handler, you:
-
-- Try to retrieve the cart from the Medusa application. The `retrieveCart` function is already available in the Next.js storefront. If the cart is not found, you return a 404 response.
-- Set the cart ID in a cookie using the `setCartId` function. This is also a function that is already available in the storefront.
-- Redirect the customer to the cart page. You set the country code in the URL based on the cart's shipping address or region.
-
-### Test it Out
-
-To test it out, start the Medusa application:
-
-```bash npm2yarn
-npm run dev
-```
-
-And in the Next.js Starter Storefront's directory, start the storefront:
-
-```bash npm2yarn
-npm run dev
-```
-
-Then, either open the link in an abandoned cart email or navigate to `localhost:8000/cart/recover/:cart_id` in your browser. You will be redirected to the cart page with the recovered cart.
-
-
-
-***
-
-## Next Steps
-
-You have now implemented the logic to send abandoned cart notifications in Medusa. You can implement other customizations with Medusa, such as:
-
-- [Implement Product Reviews](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/how-to-tutorials/tutorials/product-reviews/index.html.md).
-- [Implement Wishlist](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/plugins/guides/wishlist/index.html.md).
-- [Allow Custom-Item Pricing](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/examples/guides/custom-item-price/index.html.md).
-
-If you are new to Medusa, check out the [main documentation](https://docs.medusajs.com/docs/learn/index.html.md), where you will get a more in-depth learning of all the concepts you have used in this guide and more.
-
-To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/index.html.md).
-
-
# Implement Product Reviews in Medusa
In this tutorial, you'll learn how to implement product reviews in Medusa.
@@ -43466,1054 +44227,6 @@ Integrate a search engine to index and search products or other types of data in
- [Algolia](https://docs.medusajs.com/integrations/guides/algolia/index.html.md)
-# How to Build Magento Data Migration Plugin
-
-In this tutorial, you'll learn how to build a [plugin](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) that migrates data, such as products, from Magento to Medusa.
-
-Magento is known for its customization capabilities. However, its monolithic architecture imposes limitations on business requirements, often forcing development teams to implement hacky workarounds. Over time, these customizations become challenging to maintain, especially as the business scales, leading to increased technical debt and slower feature delivery.
-
-Medusa's modular architecture allows you to build a custom digital commerce platform that meets your business requirements without the limitations of a monolithic system. By migrating from Magento to Medusa, you can take advantage of Medusa's modern technology stack to build a scalable and flexible commerce platform that grows with your business.
-
-By following this tutorial, you'll create a Medusa plugin that migrates data from a Magento server to a Medusa application in minimal time. You can re-use this plugin across multiple Medusa applications, allowing you to adopt Medusa across your projects.
-
-## Summary
-
-### Prerequisites
-
-
-
-This tutorial will teach you how to:
-
-- Install and set up a Medusa application project.
-- Install and set up a Medusa plugin.
-- Implement a Magento Module in the plugin to connect to Magento's APIs and retrieve products.
- - This guide will only focus on migrating product data from Magento to Medusa. You can extend the implementation to migrate other data, such as customers, orders, and more.
-- Trigger data migration from Magento to Medusa in a scheduled job.
-
-You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.
-
-
-
-[Example Repository](https://github.com/medusajs/examples/tree/main/migrate-from-magento): Find the full code of the guide in this repository. The repository also includes additional features, such as triggering migrations from the Medusa Admin dashboard.
-
-***
-
-## Step 1: Install a Medusa Application
-
-You'll first install a Medusa application that exposes core commerce features through REST APIs. You'll later install the Magento plugin in this application to test it out.
-
-### 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
-```
-
-You'll be asked for the project's name. You can also optionally choose to install the [Next.js starter storefront](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/nextjs-starter/index.html.md).
-
-Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name. If you chose to install the Next.js starter, it'll be installed in a separate directory with the `{project-name}-storefront` name.
-
-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). Refer to the [Medusa Architecture](https://docs.medusajs.com/docs/learn/introduction/architecture/index.html.md) documentation to learn more.
-
-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: Install a Medusa Plugin Project
-
-A plugin is a package of reusable Medusa customizations that you can install in any Medusa application. You can add in the plugin [API Routes](https://docs.medusajs.com/docs/learn/fundamentals/api-routes/index.html.md), [Workflows](https://docs.medusajs.com/docs/learn/fundamentals/workflows/index.html.md), and other customizations, as you'll see in this guide. Afterward, you can test it out locally in a Medusa application, then publish it to npm to install and use it in any Medusa application.
-
-Refer to the [Plugins](https://docs.medusajs.com/docs/learn/fundamentals/plugins/index.html.md) documentation to learn more about plugins.
-
-A Medusa plugin is set up in a different project, giving you the flexibility in building and publishing it, while providing you with the tools to test it out locally in a Medusa application.
-
-To create a new Medusa plugin project, run the following command in a directory different than that of the Medusa application:
-
-```bash npm2yarn
-npx create-medusa-app@latest medusa-plugin-magento --plugin
-```
-
-Where `medusa-plugin-magento` is the name of the plugin's directory and the name set in the plugin's `package.json`. So, if you wish to publish it to NPM later under a different name, you can change it here in the command or later in `package.json`.
-
-Once the installation process is done, a new directory named `medusa-plugin-magento` will be created with the plugin project files.
-
-
-
-***
-
-## Step 3: Set up Plugin in Medusa Application
-
-Before you start your development, you'll set up the plugin in the Medusa application you installed in the first step. This will allow you to test the plugin during your development process.
-
-In the plugin's directory, run the following command to publish the plugin to the local package registry:
-
-```bash title="Plugin project"
-npx medusa plugin:publish
-```
-
-This command uses [Yalc](https://github.com/wclr/yalc) under the hood to publish the plugin to a local package registry. The plugin is published locally under the name you specified in `package.json`.
-
-Next, you'll install the plugin in the Medusa application from the local registry.
-
-If you've installed your Medusa project before v2.3.1, you must install [yalc](https://github.com/wclr/yalc) as a development dependency first.
-
-Run the following command in the Medusa application's directory to install the plugin:
-
-```bash title="Medusa application"
-npx medusa plugin:add medusa-plugin-magento
-```
-
-This command installs the plugin in the Medusa application from the local package registry.
-
-Next, register the plugin in the `medusa-config.ts` file of the Medusa application:
-
-```ts title="medusa-config.ts"
-module.exports = defineConfig({
- // ...
- plugins: [
- {
- resolve: "medusa-plugin-magento",
- options: {
- // TODO add options
- },
- },
- ],
-})
-```
-
-You add the plugin to the array of plugins. Later, you'll pass options useful to retrieve data from Magento.
-
-Finally, to ensure your plugin's changes are constantly published to the local registry, simplifying your testing process, keep the following command running in the plugin project during development:
-
-```bash title="Plugin project"
-npx medusa plugin:develop
-```
-
-***
-
-## Step 4: Implement Magento Module
-
-To connect to external applications in Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.
-
-In this step, you'll create a Magento Module in the Magento plugin that connects to a Magento server's REST APIs and retrieves data, such as products.
-
-Refer to the [Modules](https://docs.medusajs.com/docs/learn/fundamentals/modules/index.html.md) documentation to learn more about modules.
-
-### Create Module Directory
-
-A module is created under the `src/modules` directory of your plugin. So, create the directory `src/modules/magento`.
-
-
-
-### Create Module's Service
-
-You define a module's functionalities in a service. A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to external systems or the database, which is useful if your module defines tables in the database.
-
-In this section, you'll create the Magento Module's service that connects to Magento's REST APIs and retrieves data.
-
-Start by creating the file `src/modules/magento/service.ts` in the plugin with the following content:
-
-
-
-```ts title="src/modules/magento/service.ts"
-type Options = {
- baseUrl: string
- storeCode?: string
- username: string
- password: string
- migrationOptions?: {
- imageBaseUrl?: string
- }
-}
-
-export default class MagentoModuleService {
- private options: Options
-
- constructor({}, options: Options) {
- this.options = {
- ...options,
- storeCode: options.storeCode || "default",
- }
- }
-}
-```
-
-You create a `MagentoModuleService` that has an `options` property to store the module's options. These options include:
-
-- `baseUrl`: The base URL of the Magento server.
-- `storeCode`: The store code of the Magento store, which is `default` by default.
-- `username`: The username of a Magento admin user to authenticate with the Magento server.
-- `password`: The password of the Magento admin user.
-- `migrationOptions`: Additional options useful for migrating data, such as the base URL to use for product images.
-
-The service's constructor accepts as a first parameter the [Module Container](https://docs.medusajs.com/docs/learn/fundamentals/modules/container/index.html.md), which allows you to access resources available for the module. As a second parameter, it accepts the module's options.
-
-### Add Authentication Logic
-
-To authenticate with the Magento server, you'll add a method to the service that retrieves an access token from Magento using the username and password in the options. This access token is used in subsequent requests to the Magento server.
-
-First, add the following property to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
- private accessToken: {
- token: string
- expiresAt: Date
- }
- // ...
-}
-```
-
-You add an `accessToken` property to store the access token and its expiration date. The access token Magento returns expires after four hours, so you store the expiration date to know when to refresh the token.
-
-Next, add the following `authenticate` method to the `MagentoModuleService` class:
-
-```ts title="src/modules/magento/service.ts"
-import { MedusaError } from "@medusajs/framework/utils"
-
-export default class MagentoModuleService {
- // ...
- async authenticate() {
- const response = await fetch(`${this.options.baseUrl}/rest/${this.options.storeCode}/V1/integration/admin/token`, {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- },
- body: JSON.stringify({ username: this.options.username, password: this.options.password }),
- })
-
- const token = await response.text()
-
- if (!response.ok) {
- throw new MedusaError(MedusaError.Types.UNAUTHORIZED, `Failed to authenticate with Magento: ${token}`)
- }
-
- this.accessToken = {
- token: token.replaceAll("\"", ""),
- expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours in milliseconds
- }
- }
-}
-```
-
-You create an `authenticate` method that sends a POST request to the Magento server's `/rest/{storeCode}/V1/integration/admin/token` endpoint, passing the username and password in the request body.
-
-If the request is successful, you store the access token and its expiration date in the `accessToken` property. If the request fails, you throw a `MedusaError` with the error message returned by Magento.
-
-Lastly, add an `isAccessTokenExpired` method that checks if the access token has expired:
-
-```ts title="src/modules/magento/service.ts"
-export default class MagentoModuleService {
- // ...
- async isAccessTokenExpired(): PromiseHi {{customer.first_name}}, your cart is waiting! 🛍️
-
-
- {{#each items}}
-
-
-
- {{/each}}
-
- Return to Cart & Checkout
-
-
- {{product_title}}
-
- {{subtitle}}
-Quantity: {{quantity}}
-Price: $ {{unit_price}}
-
+
+ {title}
+
+
+ {isValueString ? (
+
+ {value ?? "-"}
+
+ ) : (
+
+ )
+}
+```
+
+The `SectionRow` component shows a title and a value in the same row.
+
+It accepts the following props:
+
+- title: (\`string\`) The title to show on the left side.
+- value: (\`React.ReactNode\` \\| \`string\` \\| \`null\`) The value to show on the right side.
+- actions: (\`React.ReactNode\`) The actions to show at the end of the row.
+
+***
+
+## Example
+
+Use the `SectionRow` component in any widget or UI route.
+
+For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
+
+```tsx title="src/admin/widgets/product-widget.tsx"
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container } from "../components/container"
+import { Header } from "../components/header"
+import { SectionRow } from "../components/section-row"
+
+const ProductWidget = () => {
+ return (
+ {value}
+ )}
+
+ {actions && {actions}
}
+
+
+ )
+}
+```
+
+The `Header` component shows a title, and optionally a subtitle and action buttons.
+
+The component also uses the [Action Menu](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/action-menu/index.html.md) custom component.
+
+It accepts the following props:
+
+- title: (\`string\`) The section's title.
+- subtitle: (\`string\`) The section's subtitle.
+- actions: (\`object\[]\`) An array of actions to show.
+
+ - type: (\`button\` \\| \`action-menu\` \\| \`custom\`) The type of action to add.
+
+ \- If its value is \`button\`, it'll show a button that can have a link or an on-click action.
+
+ \- If its value is \`action-menu\`, it'll show a three dot icon with a dropdown of actions.
+
+ \- If its value is \`custom\`, you can pass any React nodes to render.
+
+ - props: (object)
+
+ - children: (React.ReactNode) This property is only accepted if \`type\` is \`custom\`. Its content is rendered as part of the actions.
+
+***
+
+## Example
+
+Use the `Header` component in any widget or UI route.
+
+For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
+
+```tsx title="src/admin/widgets/product-widget.tsx"
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container } from "../components/container"
+import { Header } from "../components/header"
+
+const ProductWidget = () => {
+ return (
+
+ {title}
+ {subtitle && (
+
+ {subtitle}
+
+ )}
+
+ {actions.length > 0 && (
+
+ {actions.map((action, index) => (
+ <>
+ {action.type === "button" && (
+
+ )}
+ {action.type === "action-menu" && (
+
+ )}
+
-
- )
-}
-```
-
-The `Header` component shows a title, and optionally a subtitle and action buttons.
-
-The component also uses the [Action Menu](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/admin-components/components/action-menu/index.html.md) custom component.
-
-It accepts the following props:
-
-- title: (\`string\`) The section's title.
-- subtitle: (\`string\`) The section's subtitle.
-- actions: (\`object\[]\`) An array of actions to show.
-
- - type: (\`button\` \\| \`action-menu\` \\| \`custom\`) The type of action to add.
-
- \- If its value is \`button\`, it'll show a button that can have a link or an on-click action.
-
- \- If its value is \`action-menu\`, it'll show a three dot icon with a dropdown of actions.
-
- \- If its value is \`custom\`, you can pass any React nodes to render.
-
- - props: (object)
-
- - children: (React.ReactNode) This property is only accepted if \`type\` is \`custom\`. Its content is rendered as part of the actions.
-
-***
-
-## Example
-
-Use the `Header` component in any widget or UI route.
-
-For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
-
-```tsx title="src/admin/widgets/product-widget.tsx"
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container } from "../components/container"
-import { Header } from "../components/header"
-
-const ProductWidget = () => {
- return (
-
- {title}
- {subtitle && (
-
- {subtitle}
-
- )}
-
- {actions.length > 0 && (
-
- {actions.map((action, index) => (
- <>
- {action.type === "button" && (
-
- )}
- {action.type === "action-menu" && (
-
- )}
-
-
- {title}
-
-
- {isValueString ? (
-
- {value ?? "-"}
-
- ) : (
-
- )
-}
-```
-
-The `SectionRow` component shows a title and a value in the same row.
-
-It accepts the following props:
-
-- title: (\`string\`) The title to show on the left side.
-- value: (\`React.ReactNode\` \\| \`string\` \\| \`null\`) The value to show on the right side.
-- actions: (\`React.ReactNode\`) The actions to show at the end of the row.
-
-***
-
-## Example
-
-Use the `SectionRow` component in any widget or UI route.
-
-For example, create the widget `src/admin/widgets/product-widget.tsx` with the following content:
-
-```tsx title="src/admin/widgets/product-widget.tsx"
-import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container } from "../components/container"
-import { Header } from "../components/header"
-import { SectionRow } from "../components/section-row"
-
-const ProductWidget = () => {
- return (
- {value}
- )}
-
- {actions && {actions}
}
- Just Getting Started?
@@ -56047,125 +56808,6 @@ How to install and setup Medusa UI. -# Medusa Admin Extension - -How to install and use Medusa UI for building Admin extensions. - -## Installation - -*** - -The `@medusajs/ui` package is a already installed as a dependency of the `@medusajs/admin` package. Due to this you can simply import the package and use it in your local Admin extensions. - -If you are building a Admin extension as part of a Medusa plugin, you can install the package as a dependency of your plugin. - -```bash -npm install @medusajs/ui -``` - -## Configuration - -*** - -The configuration of the UI package is handled by the `@medusajs/admin` package. Therefore, you do not need to any additional configuration to use the UI package in your Admin extensions. - - -# Standalone Project - -How to install and use Medusa UI in a standalone project. - -## Installation - -*** - -Medusa UI is a React UI library and while it's intended for usage within Medusa projects, it can also be used in any React project. - -### Install Medusa UI - -Install the React UI library with the following command: - -```bash -npm install @medusajs/ui -``` - -### Configuring Tailwind CSS - -The components are styled using Tailwind CSS, and in order to use them, you will need to install Tailwind CSS in your project as well. -For more information on how to install Tailwind CSS, please refer to the [Tailwind CSS documentation](https://tailwindcss.com/docs/installation). - -All of the classes used for Medusa UI are shipped as a Tailwind CSS customization. -You can install it with the following command: - -```bash -npm install @medusajs/ui-preset -``` - -After you have installed Tailwind CSS and the Medusa UI preset, you need to add the following to your `tailwind.config.js`file: - -```tsx -module.exports = { - presets: [require("@medusajs/ui-preset")], - // ... -} -``` - -In order for the styles to be applied correctly to the components, you will also need to ensure that -`@medusajs/ui` is included in the content field of your `tailwind.config.js` file: - -```tsx -module.exports = { - content: [ - // ... - "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}", - ], - // ... -} -``` - -If you are working within a monorepo, you may need to add the path to the `@medusajs/ui` package in your `tailwind.config.js` like so: - -```tsx -const path = require("path") - -const uiPath = path.resolve( - require.resolve("@medusajs/ui"), - "../..", - "\*_/_.{js,jsx,ts,tsx}" -) - -module.exports = { - content: [ - // ... - uiPath, - ], - // ... -} - -``` - -## Start building - -*** - -You are now ready to start building your application with Medusa UI. You can import the components like so: - -```tsx -import { Button, Drawer } from "@medusajs/ui" -``` - -## Updating UI Packages - -*** - -Medusa's design-system packages, including `@medusajs/ui`, `@medusajs/ui-preset`, and `@medusajs/ui-icons`, are versioned independently. However, they're still part of the latest Medusa release. So, you can browse the [release notes](https://github.com/medusajs/medusa/releases) to see if there are any breaking changes to these packages. - -To update these packages, update their version in your `package.json` file and re-install dependencies. For example: - -```bash -npm install @medusajs/ui -``` - - # Alert A component for displaying important messages. @@ -62555,6 +63197,125 @@ If you're using the `Tooltip` component in a project other than the Medusa Admin - disableHoverableContent: (boolean) When \`true\`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. +# Medusa Admin Extension + +How to install and use Medusa UI for building Admin extensions. + +## Installation + +*** + +The `@medusajs/ui` package is a already installed as a dependency of the `@medusajs/admin` package. Due to this you can simply import the package and use it in your local Admin extensions. + +If you are building a Admin extension as part of a Medusa plugin, you can install the package as a dependency of your plugin. + +```bash +npm install @medusajs/ui +``` + +## Configuration + +*** + +The configuration of the UI package is handled by the `@medusajs/admin` package. Therefore, you do not need to any additional configuration to use the UI package in your Admin extensions. + + +# Standalone Project + +How to install and use Medusa UI in a standalone project. + +## Installation + +*** + +Medusa UI is a React UI library and while it's intended for usage within Medusa projects, it can also be used in any React project. + +### Install Medusa UI + +Install the React UI library with the following command: + +```bash +npm install @medusajs/ui +``` + +### Configuring Tailwind CSS + +The components are styled using Tailwind CSS, and in order to use them, you will need to install Tailwind CSS in your project as well. +For more information on how to install Tailwind CSS, please refer to the [Tailwind CSS documentation](https://tailwindcss.com/docs/installation). + +All of the classes used for Medusa UI are shipped as a Tailwind CSS customization. +You can install it with the following command: + +```bash +npm install @medusajs/ui-preset +``` + +After you have installed Tailwind CSS and the Medusa UI preset, you need to add the following to your `tailwind.config.js`file: + +```tsx +module.exports = { + presets: [require("@medusajs/ui-preset")], + // ... +} +``` + +In order for the styles to be applied correctly to the components, you will also need to ensure that +`@medusajs/ui` is included in the content field of your `tailwind.config.js` file: + +```tsx +module.exports = { + content: [ + // ... + "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}", + ], + // ... +} +``` + +If you are working within a monorepo, you may need to add the path to the `@medusajs/ui` package in your `tailwind.config.js` like so: + +```tsx +const path = require("path") + +const uiPath = path.resolve( + require.resolve("@medusajs/ui"), + "../..", + "\*_/_.{js,jsx,ts,tsx}" +) + +module.exports = { + content: [ + // ... + uiPath, + ], + // ... +} + +``` + +## Start building + +*** + +You are now ready to start building your application with Medusa UI. You can import the components like so: + +```tsx +import { Button, Drawer } from "@medusajs/ui" +``` + +## Updating UI Packages + +*** + +Medusa's design-system packages, including `@medusajs/ui`, `@medusajs/ui-preset`, and `@medusajs/ui-icons`, are versioned independently. However, they're still part of the latest Medusa release. So, you can browse the [release notes](https://github.com/medusajs/medusa/releases) to see if there are any breaking changes to these packages. + +To update these packages, update their version in your `package.json` file and re-install dependencies. For example: + +```bash +npm install @medusajs/ui +``` + + # clx Utility function for working with classNames. diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index dee991f3ad..7261687ebc 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -128,6 +128,11 @@ export const sidebars = [ type: "category", title: "Framework", children: [ + { + type: "link", + path: "/learn/fundamentals/framework", + title: "Overview", + }, { type: "link", path: "/learn/fundamentals/medusa-container", diff --git a/www/packages/docs-ui/src/components/SplitLists/index.tsx b/www/packages/docs-ui/src/components/SplitLists/index.tsx new file mode 100644 index 0000000000..74757aadf8 --- /dev/null +++ b/www/packages/docs-ui/src/components/SplitLists/index.tsx @@ -0,0 +1,49 @@ +import React, { useMemo } from "react" +import { Link } from "../Link" + +type SplitListItem = { + title: string + link: string + description?: string +} + +export type SplitListProps = { + items: SplitListItem[] + listsNum?: number +} + +export const SplitList = ({ items, listsNum = 2 }: SplitListProps) => { + const lists = useMemo(() => { + const lists: SplitListItem[][] = new Array(listsNum).fill(0).map(() => []) + // Split the items into listsNum lists + // by pushing each item into the list at index i % listsNum + // where i is the index of the item in the items array + // This will create a round-robin distribution of the items + // across the lists + // For example, if items = [1, 2, 3, 4, 5] and listsNum = 2 + // the result will be [[1, 3, 5], [2, 4]] + items.forEach((item, index) => { + lists[index % listsNum].push(item) + }) + return lists + }, [items, listsNum]) + + return ( +
+ {lists.map((list, index) => (
+
+ )
+}
diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts
index 5791ed9b34..f9d9dd2a90 100644
--- a/www/packages/docs-ui/src/components/index.ts
+++ b/www/packages/docs-ui/src/components/index.ts
@@ -70,6 +70,7 @@ export * from "./Select"
export * from "./Sidebar"
export * from "./Sidebar/Item"
export * from "./SourceCodeLink"
+export * from "./SplitLists"
export * from "./Table"
export * from "./Tabs"
export * from "./TextArea"
diff --git a/www/packages/docs-utils/src/get-clean-md.ts b/www/packages/docs-utils/src/get-clean-md.ts
index 8175c6fbe4..d3df31dacf 100644
--- a/www/packages/docs-utils/src/get-clean-md.ts
+++ b/www/packages/docs-utils/src/get-clean-md.ts
@@ -20,6 +20,7 @@ import {
parsePackageInstall,
parsePrerequisites,
parseSourceCodeLink,
+ parseSplitList,
parseTable,
parseTabs,
parseTypeList,
@@ -46,6 +47,7 @@ const parsers: Record-
+ {list.map((item) => (
+
-
+ {item.title}
+ {item.description && (
+ <>
+ :
{item.description}
+ + )} +
+ ))}
+