docs: add documentation for v1.8 (#3669)
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
0cca13779d
commit
c6bfad14d8
123 files changed
+7610
-2697
No files matched your search
@@ -47,9 +47,7 @@ Check out the [Event Reference](../../development/events/events-list.md) to lear
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed you already have a Medusa backend installed. If not, please follow the [Quickstart guide](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
In addition, make sure to have Redis installed and configured with your Medusa backend. If not, follow [this documentation](../../development/backend/prepare-environment.mdx#redis) to install Redis and then [configure it](../../development/backend/configurations.md#redis).
|
||||
It is assumed you already have a Medusa backend installed. If not, please follow the [Quickstart guide](../../development/backend/install.mdx) to get started in minutes. The Medusa backend must also have an event bus module installed, which is available when using the default Medusa starter.
|
||||
|
||||
### Segment Account
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ By integrating Contentful to Medusa, you can benefit from powerful features in y
|
||||
### Required Tools
|
||||
|
||||
- PostgreSQL with an empty database created. You can follow [this documentation to learn how to install it for your operating system](../../../development/backend/prepare-environment.mdx#postgres).
|
||||
- Redis. You can follow [this documentation to learn how to install it for your operating system](../../../development/backend/prepare-environment.mdx#redis).
|
||||
- Redis. You can follow [their documentation to learn how to install it](https://redis.io/docs/getting-started/installation/).
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../../development/backend/prepare-environment.mdx#git).
|
||||
- Gatsby’s CLI tool. You can follow [this documentation to install it](https://www.gatsbyjs.com/docs/reference/gatsby-cli/#how-to-use-gatsby-cli).
|
||||
- Medusa’s CLI tool. You can follow [this documentation to install it](../../../cli/reference.md#how-to-install-cli-tool).
|
||||
|
||||
@@ -29,9 +29,7 @@ By integrating SendGrid with Medusa, you’ll be sending email notifications to
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before going further with this guide make sure you have a Medusa backend set up. You can follow the [Quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
You also must have [Redis configured on your Medusa backend](../../development/backend/prepare-environment.mdx#redis). Sending emails is done through Subscribers, which uses Redis as the event queue. If you don’t set up Redis, the plugin will not send emails.
|
||||
Before going further with this guide make sure you have a Medusa backend set up. You can follow the [Quickstart guide](../../development/backend/install.mdx). The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -32,15 +32,7 @@ To follow along with this guide, you need to have a Slack account with a connect
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
This tutorial assumes you already have a Medusa backend installed. If you don’t, please follow along with the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
### Redis
|
||||
|
||||
Medusa's event system works by pushing data into a queue that is based on [Redis](https://redis.io/). This queue then notifies handlers of different events of this data that is pushed into the queue. The handlers then use this data to perform a certain action.
|
||||
|
||||
As the Slack plugin will listen to the `order.placed` event to know when to send notifications, you'll need to have Redis installed and configured with your Medusa backend.
|
||||
|
||||
You can read the [Set up your development enviornment guideline](../../development/backend/prepare-environment.mdx#redis) to learn more about how you can install and setup Redis.
|
||||
This tutorial assumes you already have a Medusa backend installed. If you don’t, please follow along with the [quickstart guide](../../development/backend/install.mdx). The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ In this example, you’ll create a subscriber that listens to the `order.placed`
|
||||
|
||||
:::tip
|
||||
|
||||
For this example to work, you’ll need to install and configure Redis on your backend. You can refer to the [development guide](../../development/backend/prepare-environment.mdx#redis) to learn how to do that.
|
||||
For this example to work, you'll need to have an event bus module installed and configured, which should be available by default.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -7,6 +7,12 @@ addHowToData: true
|
||||
|
||||
In this document, you’ll learn how to integrate Klarna as a payment provider in Medusa.
|
||||
|
||||
:::tip
|
||||
|
||||
Following the release of v1.8 of the core Medusa package, the naming of payment providers have changed to payment processors with the introduction of the Payment Processor API. However, plugins or implementation that still don't implement the Payment Processor API are still called payment providers.
|
||||
|
||||
:::
|
||||
|
||||
## Introduction
|
||||
|
||||
[Klarna](https://www.klarna.com/) is a payment provider that allows customers to pay in different ways including direct payment, installment payments, payment after delivery, and more.
|
||||
|
||||
@@ -5,15 +5,15 @@ addHowToData: true
|
||||
|
||||
# PayPal
|
||||
|
||||
This document guides you through setting up PayPal as a payment provider in your Medusa backend, admin, and storefront using the [PayPal plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-paypal).
|
||||
This document guides you through setting up PayPal as a payment processor in your Medusa backend, admin, and storefront using the [PayPal plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-paypal).
|
||||
|
||||
## Overview
|
||||
|
||||
[PayPal](https://www.paypal.com) is a payment provider used by millions around the world. It allows customers to purchase orders from your website using their PayPal account rather than the need to enter their card details.
|
||||
[PayPal](https://www.paypal.com) is a payment processor used by millions around the world. It allows customers to purchase orders from your website using their PayPal account rather than the need to enter their card details.
|
||||
|
||||
As a developer, you can use PayPal’s SDKs and APIs to integrate PayPal as a payment method into your ecommerce store. You can test out the payment method in sandbox mode before going live with it as a payment method.
|
||||
|
||||
Using the `medusa-payment-paypal` plugin, this guide shows you how to set up your Medusa backend with PayPal as a payment provider.
|
||||
Using the `medusa-payment-paypal` plugin, this guide shows you how to set up your Medusa backend with PayPal as a payment processor.
|
||||
|
||||
---
|
||||
|
||||
@@ -27,7 +27,7 @@ Webhooks are used in scenarios where the customer might leave the page during th
|
||||
|
||||
Additionally, you need a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../development/backend/install.mdx) to get started.
|
||||
|
||||
You also need [Medusa Admin](../../admin/quickstart.mdx) installed to enable PayPal as a payment provider. You can alternatively use the [REST APIs](/api/admin).
|
||||
You also need [Medusa Admin](../../admin/quickstart.mdx) installed to enable PayPal as a payment processor. You can alternatively use the [REST APIs](/api/admin).
|
||||
|
||||
---
|
||||
|
||||
@@ -81,9 +81,9 @@ That’s all you need to install PayPal on your Medusa backend!
|
||||
|
||||
## Admin Setup
|
||||
|
||||
This section will guide you through adding PayPal as a payment provider in a region using your Medusa admin dashboard.
|
||||
This section will guide you through adding PayPal as a payment processor in a region using your Medusa admin dashboard.
|
||||
|
||||
This step is required for you to be able to use PayPal as a payment provider in your storefront.
|
||||
This step is required for you to be able to use PayPal as a payment processor in your storefront.
|
||||
|
||||
### Admin Prerequisites
|
||||
|
||||
@@ -91,7 +91,7 @@ If you don’t have a Medusa admin installed, make sure to follow along with [th
|
||||
|
||||
### Add PayPal to Regions
|
||||
|
||||
You can refer to [this documentation in the user guide](../../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like PayPal to a region.
|
||||
You can refer to [this documentation in the user guide](../../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment processor like PayPal to a region.
|
||||
|
||||
---
|
||||
|
||||
@@ -115,7 +115,7 @@ It is recommended to read through the [Frontend Checkout Flow](../../modules/car
|
||||
|
||||
Although the next sections have different implementations to add PayPal into your storefront, they essentially follow the same process:
|
||||
|
||||
1. Show PayPal’s button if the PayPal provider is available for the current cart.
|
||||
1. Show PayPal’s button if the PayPal processor is available for the current cart.
|
||||
2. When the button is clicked, open PayPal’s payment portal and wait for the customer to authorize the payment.
|
||||
3. If the payment is authorized successfully, set PayPal’s [Payment Session](../../modules/carts-and-checkout/payment.md#payment-session) as the session used to perform the payment for the current cart, then update the Payment Session on the backend with the data received from PayPal’s payment portal. This data is essential to the backend to verify the authorization and perform additional payment processing later such as capturing payment.
|
||||
4. Complete the cart to create the order.
|
||||
@@ -169,7 +169,7 @@ Next, create a new file `src/components/payment/paypal-payment/index.jsx` with t
|
||||
```jsx title=src/components/payment/paypal-payment/index.jsx
|
||||
import {
|
||||
PayPalButtons,
|
||||
PayPalScriptProvider,
|
||||
PayPalScriptProcessor,
|
||||
} from "@paypal/react-paypal-js"
|
||||
import React, { useMemo, useState } from "react"
|
||||
|
||||
@@ -192,7 +192,7 @@ const PaypalPayment = () => {
|
||||
const paypalSession = useMemo(() => {
|
||||
if (cart.payment_sessions) {
|
||||
return cart.payment_sessions.find(
|
||||
(s) => s.provider_id === "paypal"
|
||||
(s) => s.processor_id === "paypal"
|
||||
)
|
||||
}
|
||||
|
||||
@@ -245,7 +245,7 @@ const PaypalPayment = () => {
|
||||
}
|
||||
|
||||
return (
|
||||
<PayPalScriptProvider options={{
|
||||
<PayPalScriptProcessor options={{
|
||||
"client-id": paypalClientId,
|
||||
"currency": cart.region.currency_code.toUpperCase(),
|
||||
"intent": "authorize",
|
||||
@@ -260,7 +260,7 @@ const PaypalPayment = () => {
|
||||
onApprove={handlePayment}
|
||||
disabled={processing}
|
||||
/>
|
||||
</PayPalScriptProvider>
|
||||
</PayPalScriptProcessor>
|
||||
)
|
||||
}
|
||||
|
||||
@@ -269,18 +269,18 @@ export default PaypalPayment
|
||||
|
||||
Here’s briefly what this code snippet does:
|
||||
|
||||
1. This component renders a PayPal button to initialize the payment using PayPal. You use the components from the PayPal React components library to render the button and you pass the `PayPalScriptProvider` component the Client ID.
|
||||
1. This component renders a PayPal button to initialize the payment using PayPal. You use the components from the PayPal React components library to render the button and you pass the `PayPalScriptProcessor` component the Client ID.
|
||||
2. When the button is clicked, the `handlePayment` function is executed. In this method, you initialize the payment authorization using `actions.order.authorize()`. It takes the customer to another page to log in with PayPal and authorize the payment.
|
||||
3. After the payment is authorized successfully on PayPal’s portal, the fulfillment function passed to `actions.order.authorize().then` will be executed which calls the `completeOrder` function.
|
||||
4. In `completeOrder`, you first ensure that the payment session for the PayPal payment provider is set as the [selected Payment Session in the cart](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession). Then, you send a request to the backend to [update the payment session](/api/store#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) data with the authorization data received from PayPal.
|
||||
4. In `completeOrder`, you first ensure that the payment session for the PayPal payment processor is set as the [selected Payment Session in the cart](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession). Then, you send a request to the backend to [update the payment session](/api/store#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) data with the authorization data received from PayPal.
|
||||
5. You then [complete the cart and place the order](/api/store/#tag/Cart/operation/PostCartsCartComplete). If that is done successfully, you navigate to the `/order-confirmed` page.
|
||||
|
||||
The last step is to add this component as the component to render when PayPal is available as a payment provider.
|
||||
The last step is to add this component as the component to render when PayPal is available as a payment processor.
|
||||
|
||||
In `src/components/payment/index.js` you’ll find in the return statement a switch statement that checks the payment provider for each payment session and renders the component based on the ID. Add before the `default` case a case for `paypal`:
|
||||
In `src/components/payment/index.js` you’ll find in the return statement a switch statement that checks the payment processor for each payment session and renders the component based on the ID. Add before the `default` case a case for `paypal`:
|
||||
|
||||
```jsx title=src/components/payment/index.js
|
||||
switch (ps.provider_id) {
|
||||
switch (ps.processor_id) {
|
||||
case "stripe":
|
||||
// ...
|
||||
break
|
||||
@@ -325,7 +325,7 @@ Next, create the file that will hold the PayPal component with the following con
|
||||
```jsx
|
||||
import {
|
||||
PayPalButtons,
|
||||
PayPalScriptProvider,
|
||||
PayPalScriptProcessor,
|
||||
} from "@paypal/react-paypal-js"
|
||||
import { useEffect, useState } from "react"
|
||||
|
||||
@@ -350,7 +350,7 @@ function Paypal() {
|
||||
const response = await client
|
||||
.carts
|
||||
.setPaymentSession(cart.id, {
|
||||
"provider_id": "paypal",
|
||||
"processor_id": "paypal",
|
||||
})
|
||||
|
||||
if (!response.cart) {
|
||||
@@ -383,7 +383,7 @@ function Paypal() {
|
||||
return (
|
||||
<div style={{ marginTop: "10px", marginLeft: "10px" }}>
|
||||
{cart !== undefined && (
|
||||
<PayPalScriptProvider options={{
|
||||
<PayPalScriptProcessor options={{
|
||||
"client-id": "<CLIENT_ID>",
|
||||
"currency": "EUR",
|
||||
"intent": "authorize",
|
||||
@@ -398,7 +398,7 @@ function Paypal() {
|
||||
onApprove={handlePayment}
|
||||
disabled={processing}
|
||||
/>
|
||||
</PayPalScriptProvider>
|
||||
</PayPalScriptProcessor>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
@@ -411,10 +411,10 @@ Here’s briefly what this code snippet does:
|
||||
|
||||
1. At the beginning of the component, the Medusa client is initialized using the JS Client you installed.
|
||||
2. You also need to retrieve the cart. Ideally, the cart should be managed through a context. So, every time the cart has been updated the cart should be updated in the context to be accessed from all components.
|
||||
3. This component renders a PayPal button to initialize the payment using PayPal. You use the components from the PayPal React components library to render the button and you pass the `PayPalScriptProvider` component the Client ID. Make sure to replace `<CLIENT_ID>` with the environment variable you added.
|
||||
3. This component renders a PayPal button to initialize the payment using PayPal. You use the components from the PayPal React components library to render the button and you pass the `PayPalScriptProcessor` component the Client ID. Make sure to replace `<CLIENT_ID>` with the environment variable you added.
|
||||
4. When the button is clicked, the `handlePayment` function is executed. In this method, you initialize the payment authorization using `actions.order.authorize()`. It takes the customer to another page to log in with PayPal and authorize the payment.
|
||||
5. After the payment is authorized successfully on PayPal’s portal, the fulfillment function passed to `actions.order.authorize().then` will be executed.
|
||||
6. In the fulfillment function, you first ensure that the payment session for the PayPal payment provider is set as the [selected Payment Session in the cart](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession). Then, you send a request to the backend to [update the payment session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) data with the authorization data received from PayPal.
|
||||
6. In the fulfillment function, you first ensure that the payment session for the PayPal payment processor is set as the [selected Payment Session in the cart](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession). Then, you send a request to the backend to [update the payment session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) data with the authorization data received from PayPal.
|
||||
7. You then [complete the cart and place the order](/api/store/#tag/Cart/operation/PostCartsCartComplete). If that is done successfully, you just show a success alert. You can change this based on the behavior you want in your storefront.
|
||||
|
||||
You can then import this component where you want to show it in your storefront.
|
||||
|
||||
@@ -21,7 +21,7 @@ You can also follow this video guide to learn how the setup works:
|
||||
|
||||
[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern-free development process.
|
||||
|
||||
Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment provider.
|
||||
Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment processor.
|
||||
|
||||
---
|
||||
|
||||
@@ -33,7 +33,7 @@ Before you proceed with this guide, make sure you create a [Stripe account](http
|
||||
|
||||
## Medusa Backend
|
||||
|
||||
This section guides you over the steps necessary to add Stripe as a payment provider to your Medusa backend.
|
||||
This section guides you over the steps necessary to add Stripe as a payment processor to your Medusa backend.
|
||||
|
||||
If you don’t have a Medusa backend installed yet, you must follow the [quickstart guide](../../development/backend/install.mdx) first.
|
||||
|
||||
@@ -86,7 +86,7 @@ STRIPE_API_KEY=sk_...
|
||||
|
||||
:::note
|
||||
|
||||
If you store environment variables differently on your backend, for example, using the hosting provider’s UI, then you don’t need to add it in `.env`. Add the environment variables in a way relevant to your backend.
|
||||
If you store environment variables differently on your backend, for example, using the hosting processor’s UI, then you don’t need to add it in `.env`. Add the environment variables in a way relevant to your backend.
|
||||
|
||||
:::
|
||||
|
||||
@@ -108,9 +108,9 @@ STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
|
||||
## Admin Setup
|
||||
|
||||
This section will guide you through adding Stripe as a payment provider in a region using your Medusa admin dashboard.
|
||||
This section will guide you through adding Stripe as a payment processor in a region using your Medusa admin dashboard.
|
||||
|
||||
This step is required for you to be able to use Stripe as a payment provider in your storefront.
|
||||
This step is required for you to be able to use Stripe as a payment processor in your storefront.
|
||||
|
||||
### Admin Prerequisites
|
||||
|
||||
@@ -118,7 +118,7 @@ If you don’t have a Medusa admin installed, make sure to follow along with [th
|
||||
|
||||
### Add Stripe to Regions
|
||||
|
||||
You can refer to [this documentation in the user guide](../../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like Stripe to a region.
|
||||
You can refer to [this documentation in the user guide](../../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment processor like Stripe to a region.
|
||||
|
||||
---
|
||||
|
||||
@@ -178,8 +178,8 @@ This section will go over how to add Stripe into a React-based framework. The in
|
||||
|
||||
The integration with stripe must have the following workflow:
|
||||
|
||||
1. During checkout when the user reaches the payment section, you should [create payment sessions](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions). This will initialize the `payment_sessions` array in the `cart` object received. The `payment_sessions` is an array of available payment providers.
|
||||
2. If Stripe is available as a payment provider, you should select Stripe as [the payment session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession) for the current cart. This will initialize the `payment_session` object in the `cart` object to include data related to Stripe and the current payment session. This includes the payment intent and client secret.
|
||||
1. During checkout when the user reaches the payment section, you should [create payment sessions](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions). This will initialize the `payment_sessions` array in the `cart` object received. The `payment_sessions` is an array of available payment processors.
|
||||
2. If Stripe is available as a payment processor, you should select Stripe as [the payment session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession) for the current cart. This will initialize the `payment_session` object in the `cart` object to include data related to Stripe and the current payment session. This includes the payment intent and client secret.
|
||||
3. After the user enters their card details and submits the form, confirm the payment with Stripe.
|
||||
4. If the payment is confirmed successfully, [complete the order](/api/store/#tag/Cart/operation/PostCartsCartComplete) in Medusa. Otherwise show an error.
|
||||
|
||||
@@ -299,7 +299,7 @@ client.carts.createPaymentSessions(cart.id)
|
||||
// check if stripe is selected
|
||||
const isStripeAvailable = cart.payment_sessions?.some(
|
||||
(session) => (
|
||||
session.provider_id === "stripe"
|
||||
session.processor_id === "stripe"
|
||||
)
|
||||
)
|
||||
if (!isStripeAvailable) {
|
||||
@@ -308,7 +308,7 @@ client.carts.createPaymentSessions(cart.id)
|
||||
|
||||
// select stripe payment session
|
||||
client.carts.setPaymentSession(cart.id, {
|
||||
provider_id: "stripe",
|
||||
processor_id: "stripe",
|
||||
}).then(({ cart }) => {
|
||||
setClientSecret(cart.payment_session.data.client_secret)
|
||||
})
|
||||
|
||||
@@ -23,15 +23,7 @@ Through Medusa's flexible plugin system, it is possible to add a search engine t
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It is required to have a Medusa backend installed before starting with this documentation. If not, please follow along with the [quickstart guide](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
Furthermore, it’s highly recommended to ensure your Medusa backend is configured to work with Redis. As Medusa uses Redis for the event queue internally, configuring Redis ensures that the search indices in Algolia are updated whenever products on the Medusa backend are updated. You can follow [this documentation to install Redis](../../development/backend/prepare-environment.mdx#redis) and then [configure it on your Medusa backend](../../development/backend/configurations.md#redis).
|
||||
|
||||
:::caution
|
||||
|
||||
If you don’t install and configure Redis on your Medusa backend, the Algolia integration will still work. However, products indexed in Algolia are only added and updated when you restart the Medusa backend.
|
||||
|
||||
:::
|
||||
It is required to have a Medusa backend installed before starting with this documentation. If not, please follow along with the [quickstart guide](../../development/backend/install.mdx) to get started in minutes. The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.
|
||||
|
||||
### Algolia Account
|
||||
|
||||
@@ -100,38 +92,100 @@ Where `<YOUR_APP_ID>` and `<YOUR_ADMIN_API_KEY>` are respectively the Applicatio
|
||||
|
||||
Finally, in `medusa-config.js` add the following item into the `plugins` array:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-algolia`,
|
||||
options: {
|
||||
application_id: process.env.ALGOLIA_APP_ID,
|
||||
admin_api_key: process.env.ALGOLIA_ADMIN_API_KEY,
|
||||
applicationId: process.env.ALGOLIA_APP_ID,
|
||||
adminApiKey: process.env.ALGOLIA_ADMIN_API_KEY,
|
||||
settings: {
|
||||
products: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: [
|
||||
"id",
|
||||
"title",
|
||||
"description",
|
||||
"handle",
|
||||
"thumbnail",
|
||||
"variants",
|
||||
"variant_sku",
|
||||
"options",
|
||||
"collection_title",
|
||||
"collection_handle",
|
||||
"images",
|
||||
],
|
||||
},
|
||||
// index settings...
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
The `searchableAttributes` are the attributes in a product that are searchable, and `attributesToRetrieve` are the attributes to retrieve for each product result. You’re free to make changes to these attributes as you see fit, but these are the recommended attributes.
|
||||
### Index Settings
|
||||
|
||||
Under the `settings` key of the plugin's options, you can add settings specific to each index. The settings are of the following format:
|
||||
|
||||
```js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-algolia`,
|
||||
options: {
|
||||
// other options...
|
||||
settings: {
|
||||
indexName: {
|
||||
indexSettings: {
|
||||
searchableAttributes,
|
||||
attributesToRetrieve,
|
||||
},
|
||||
transformer,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `indexName`: the name of the index to create in Algolia. For example, `products`. Its value is an object containing the following properties:
|
||||
- `indexSettings`: an object that includes the following properties:
|
||||
- `searchableAttributes`: an array of strings indicating the attributes in the product entity that can be searched.
|
||||
- `attributesToRetrieve`: an array of strings indicating the attributes in the product entity that should be retrieved in the search results.
|
||||
- `transformer`: an optional function that accepts a product as a parameter and returns an object to be indexed. This allows you to have more control over what you're indexing. For example, you can add details related to variants or custom relations, or you can filter out certain products.
|
||||
|
||||
Using this index settings structure, you can add more than one index.
|
||||
|
||||
:::tip
|
||||
|
||||
These settings are just examples of what you can pass to the Algolia provider. If you need to pass more settings to the Algolia SDK you can pass it inside `indexSettings`.
|
||||
|
||||
:::
|
||||
|
||||
Here's an example of the settings you can use:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-algolia`,
|
||||
options: {
|
||||
// other options...
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: [
|
||||
"id",
|
||||
"title",
|
||||
"description",
|
||||
"handle",
|
||||
"thumbnail",
|
||||
"variants",
|
||||
"variant_sku",
|
||||
"options",
|
||||
"collection_title",
|
||||
"collection_handle",
|
||||
"images",
|
||||
],
|
||||
},
|
||||
transform: (product) => ({
|
||||
id: product.id,
|
||||
// other attributes...
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -163,7 +217,7 @@ If you add or update products on your Medusa backend, the addition or update wil
|
||||
|
||||
:::note
|
||||
|
||||
This feature is only available if you have Redis installed and configured with your Medusa backend as mentioned in the [Prerequisites section](#prerequisites). Otherwise, you must re-run the Medusa backend to see the change in the Algolia indices.
|
||||
This feature is only available if you have an event module installed in your Medusa backend, as explained in the Prerequisites section.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -21,15 +21,7 @@ Through Medusa's flexible plugin system, it is possible to add a search engine t
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It is required to have a Medusa backend installed before starting with this documentation. If not, please follow along with the [quickstart guide](../../development/backend/install.mdx) to get started in minutes.
|
||||
|
||||
Furthermore, it’s highly recommended to ensure your Medusa backend is configured to work with Redis. As Medusa uses Redis for the event queue internally, configuring Redis ensures that the search indices in MeiliSearch are updated whenever products on the Medusa backend are updated. You can follow [this documentation to install Redis](../../development/backend/prepare-environment.mdx#redis) and then [configure it on your Medusa backend](../../development/backend/configurations.md#redis).
|
||||
|
||||
:::caution
|
||||
|
||||
If you don’t install and configure Redis on your Medusa backend, the MeiliSearch integration will still work. However, products indexed in MeiliSearch are only added and updated when you restart the Medusa backend.
|
||||
|
||||
:::
|
||||
It is required to have a Medusa backend installed before starting with this documentation. If not, please follow along with the [quickstart guide](../../development/backend/install.mdx) to get started in minutes. The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.
|
||||
|
||||
### MeiliSearch Instance
|
||||
|
||||
@@ -73,30 +65,92 @@ const plugins = [
|
||||
apiKey: process.env.MEILISEARCH_API_KEY,
|
||||
},
|
||||
settings: {
|
||||
// index name
|
||||
products: {
|
||||
// MeiliSearch's setting options
|
||||
// to be set on a particular index
|
||||
searchableAttributes: [
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
],
|
||||
displayedAttributes: [
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
"thumbnail",
|
||||
"handle",
|
||||
],
|
||||
},
|
||||
// index settings...
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
You can change the `searchableAttributes` and `displayedAttributes` as you see fit. However, the attributes included are the recommended attributes.
|
||||
### Index Settings
|
||||
|
||||
Under the `settings` key of the plugin's options, you can add settings specific to each index. The settings are of the following format:
|
||||
|
||||
```js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-meilisearch`,
|
||||
options: {
|
||||
// other options...
|
||||
settings: {
|
||||
indexName: {
|
||||
indexSettings: {
|
||||
searchableAttributes,
|
||||
displayedAttributes,
|
||||
},
|
||||
primaryKey,
|
||||
transformer,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `indexName`: the name of the index to create in MeiliSearch. For example, `products`. Its value is an object containing the following properties:
|
||||
- `indexSettings`: an object that includes the following properties:
|
||||
- `searchableAttributes`: an array of strings indicating the attributes in the product entity that can be searched.
|
||||
- `displayedAttributes`: an array of strings indicating the attributes in the product entity that should be displayed in the search results.
|
||||
- `primaryKey`: an optional string indicating which property acts as a primary key of a document. It's used to enforce unique documents in an index. The default value is `id`. You can learn more in [MeiliSearch's documentation](https://docs.meilisearch.com/learn/core_concepts/primary_key.html#primary-field).
|
||||
- `transformer`: an optional function that accepts a product as a parameter and returns an object to be indexed. This allows you to have more control over what you're indexing. For example, you can add details related to variants or custom relations, or you can filter out certain products.
|
||||
|
||||
Using this index settings structure, you can add more than one index.
|
||||
|
||||
:::tip
|
||||
|
||||
These settings are just examples of what you can pass to the MeiliSearch provider. If you need to pass more settings to the MeiliSearch SDK you can pass it inside `indexSettings`.
|
||||
|
||||
:::
|
||||
|
||||
Here's an example of the settings you can use:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-meilisearch`,
|
||||
options: {
|
||||
// other options...
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: [
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
],
|
||||
displayedAttributes: [
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
"thumbnail",
|
||||
"handle",
|
||||
],
|
||||
},
|
||||
primaryKey: "id",
|
||||
transform: (product) => ({
|
||||
id: product.id,
|
||||
// other attributes...
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -124,7 +178,7 @@ If you add or update products on your Medusa backend, the addition or update wil
|
||||
|
||||
:::note
|
||||
|
||||
This feature is only available if you have Redis installed and configured with your Medusa backend as mentioned in the [Prerequisites section](#prerequisites). Otherwise, you must re-run the Medusa backend to see the change in the MeiliSearch indices.
|
||||
This feature is only available if you have an event module installed in your Medusa backend, as explained in the Prerequisites section.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
Reference in new issue
Block a user