docs: editing and general fixes of medusa's learning resources (#7261)
* docs: editing and general fixes of medusa's learning resources * fix build script * update ui dependency * fix build * adjust next.js steps
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,232 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Algolia Plugin`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
## Features
|
||||
|
||||
[Algolia](https://www.algolia.com/) is a search engine service that allows developers to integrate advanced search functionalities into their websites including typo tolerance, recommended results, and quick responses.
|
||||
|
||||
Algolia is used for a wide range of use cases, including commerce stores. By integrating Algolia into your commerce application, you provide your customers with a better user experience and help them find what they’re looking for swifltly.
|
||||
|
||||
---
|
||||
|
||||
## Install the Algolia Plugin
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [Algolia account](https://www.algolia.com/users/sign_up)
|
||||
- [Algolia app ID](https://support.algolia.com/hc/en-us/articles/11040113398673-Where-can-I-find-my-application-ID-and-the-index-name)
|
||||
- [Algolia API key](https://support.algolia.com/hc/en-us/articles/11972559809681-How-do-I-find-my-Admin-API-key)
|
||||
|
||||
</Note>
|
||||
|
||||
To install the Algolia plugin, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-algolia
|
||||
```
|
||||
|
||||
Next, add the plugin into the `plugins` array in `medusa-config.js`:
|
||||
|
||||
export const highlights = [
|
||||
["6", "applicationId", "The Algolia app ID."],
|
||||
["7", "adminApiKey", "The Algolia API key."],
|
||||
["8", "settings", "Settings of indices created in Algolia."],
|
||||
["9", "products", "The name of an index to create. In this example, it's `products`."],
|
||||
["10", "indexSettings", "The settings of the index."],
|
||||
["11", "searchableAttributes", "The attributes that can be searched in the index."],
|
||||
["12", "attributesToRetrieve", "The attributes to retrieve in the search results."],
|
||||
["26", "transformer", "A function that shapes the object to be indexed."]
|
||||
]
|
||||
|
||||
```js title="medusa-config.js" highlights={highlights}
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-algolia`,
|
||||
options: {
|
||||
applicationId: process.env.ALGOLIA_APP_ID,
|
||||
adminApiKey: process.env.ALGOLIA_ADMIN_API_KEY,
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: ["title", "description"],
|
||||
attributesToRetrieve: [
|
||||
"id",
|
||||
"title",
|
||||
"description",
|
||||
"handle",
|
||||
"thumbnail",
|
||||
"variants",
|
||||
"variant_sku",
|
||||
"options",
|
||||
"collection_title",
|
||||
"collection_handle",
|
||||
"images",
|
||||
],
|
||||
},
|
||||
transformer: (product) => ({
|
||||
objectID: product.id,
|
||||
// other attributes...
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
### Algolia Plugin Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
<Table.HeaderCell>Required</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`applicationId`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A string indicating the Algolia app ID.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Yes
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`adminApiKey`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A string indicating the Algolia API key.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Yes
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
An object of settings. Its keys are names of indices to create in Algolia (in the example above, `products`), and values are an object of the index's settings.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
No
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings.[indexName].indexSettings`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
An object of index settings. It accepts two properties:
|
||||
|
||||
- `searchableAttributes`: An array of field names that can be searched.
|
||||
- `attributesToRetrieve`: An array of field names retrieved in search results.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
If `settings` is provided, this property is required.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings.[indexName].transformer`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A function used to change the shape of the indexed records. For example, you can add details related to variants or custom relations, or filter out certain products.
|
||||
|
||||
The function accepts as a parameter that data model object to index, such as a product, and returns an object to be indexed.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
No
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Make sure to add the necessary environment variables for the above options in `.env`:
|
||||
|
||||
```bash
|
||||
ALGOLIA_APP_ID=<YOUR_APP_ID>
|
||||
ALGOLIA_ADMIN_API_KEY=<YOUR_ADMIN_API_KEY>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test the Plugin
|
||||
|
||||
To test the plugin, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, send a `POST` request to the `/store/products/search`:
|
||||
|
||||
```bash apiTesting testApiUrl="http://localhost:9000/store/products/search" testApiMethod="POST" testBodyParams={{"q": "shirt"}}
|
||||
curl -X POST http://localhost:9000/store/products/search \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"q": "shirt"
|
||||
}'
|
||||
```
|
||||
|
||||
The response contains a `hits` array with the results from the Algolia search engine.
|
||||
|
||||
### Add or Update Products
|
||||
|
||||
If you add or update products in your Medusa application, it'll be reflected in the Algolia indices.
|
||||
|
||||
---
|
||||
|
||||
## Add Search to your Storefront
|
||||
|
||||
### Next.js Starter
|
||||
|
||||
Refer to the [Next.js Starter guide](../../../nextjs-starter/page.mdx#configure-algolia) to learn how to configure Algolia.
|
||||
|
||||
### Custom Storefront
|
||||
|
||||
To integrate Algolia's search functionalities in your custom storefront, refer to [Algolia's InstantSearch.js documentation](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/).
|
||||
@@ -0,0 +1,248 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `MeiliSearch Plugin`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
## Features
|
||||
|
||||
[MeiliSearch](https://www.meilisearch.com/) is a super-fast, open source search engine built in Rust. It comes with a wide range of features including typo-tolerance, filtering, and sorting.
|
||||
|
||||
MeiliSearch also provides a pleasant developer experience, as it is extremely intuitive and newcomer-friendly. So, even if you're new to the search engine ecosystem, [their documentation](https://docs.meilisearch.com/) is resourceful enough for everyone to go through and understand.
|
||||
|
||||
---
|
||||
|
||||
## Install the MeiliSearch Plugin
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [MeiliSearch installed](https://docs.meilisearch.com/learn/getting_started/quick_start.html#setup-and-installation)
|
||||
- [MeiliSearch master key](https://www.meilisearch.com/docs/learn/security/master_api_keys#protecting-a-meilisearch-instance)
|
||||
|
||||
</Note>
|
||||
|
||||
To install the Algolia plugin, run the following command in the directory of your Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-meilisearch
|
||||
```
|
||||
|
||||
Next, add the plugin into the `plugins` array in `medusa-config.js`:
|
||||
|
||||
export const highlights = [
|
||||
["6", "config", "The MeiliSearch connection configuration object."],
|
||||
["7", "host", "The MeiliSearch host."],
|
||||
["8", "apiKey", "The MeiliSearch master key."],
|
||||
["10", "settings", "Settings of indices created in MeiliSearch."],
|
||||
["11", "products", "The name of an index to create. In this example, it's `products`."],
|
||||
["12", "indexSettings", "The settings of the index."],
|
||||
["13", "searchableAttributes", "The attributes that can be searched in the index."],
|
||||
["18", "displayedAttributes", "The attributes to retrieve in the search results."],
|
||||
["27", "transformer", "A function that shapes the object to be indexed."]
|
||||
]
|
||||
|
||||
```js title="medusa-config.js" highlights={highlights}
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-meilisearch`,
|
||||
options: {
|
||||
config: {
|
||||
host: process.env.MEILISEARCH_HOST,
|
||||
apiKey: process.env.MEILISEARCH_API_KEY,
|
||||
},
|
||||
settings: {
|
||||
products: {
|
||||
indexSettings: {
|
||||
searchableAttributes: [
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
],
|
||||
displayedAttributes: [
|
||||
"id",
|
||||
"title",
|
||||
"description",
|
||||
"variant_sku",
|
||||
"thumbnail",
|
||||
"handle",
|
||||
],
|
||||
},
|
||||
transformer: (product) => ({
|
||||
id: product.id,
|
||||
// other attributes...
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
### MeiliSearch Plugin Options
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Option</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
<Table.HeaderCell>Required</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`config`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
An object of MeiliSearch connection configurations. It accepts two properties:
|
||||
|
||||
- `host`: A string indicating the MeiliSearch host. For example, `http://127.0.0.1:7700`.
|
||||
- `apiKey`: A string indicating the [MeiliSearch master key](https://www.meilisearch.com/docs/learn/security/master_api_keys#protecting-a-meilisearch-instance).
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Yes
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
An object of settings. Its keys are names of indices to create in MeiliSearch (in the example above, `products`), and values are an object of the index's settings.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
No
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings.[indexName].indexSettings`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
An object of index settings. It accepts two properties:
|
||||
|
||||
- `searchableAttributes`: An array of field names that can be searched.
|
||||
- `displayedAttributes`: An array of field names retrieved in search results.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
If `settings` is provided, this property is required.
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings.[indexName].transformer`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A function used to change the shape of the indexed records. For example, you can add details related to variants or custom relations, or filter out certain products.
|
||||
|
||||
The function accepts as a parameter that data model object to index, such as a product, and returns an object to be indexed.
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
No
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`settings.[indexName].primaryKey`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
A string indicating which field in the data model acts as a primary key of a document. It's used to enforce unique documents in an index. Learn more in [MeiliSearch's documentation](https://docs.meilisearch.com/learn/core_concepts/primary_key.html#primary-field).
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
`id`
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Make sure to add the necessary environment variables for the above options in `.env`:
|
||||
|
||||
```bash
|
||||
MEILISEARCH_HOST=<YOUR_MEILISEARCH_HOST>
|
||||
MEILISEARCH_API_KEY=<YOUR_MASTER_KEY>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test the Plugin
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [MeiliSearch running in the background](https://www.meilisearch.com/docs/learn/getting_started/quick_start#running-meilisearch).
|
||||
|
||||
</Note>
|
||||
|
||||
To test the plugin, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, send a `POST` request to the `/store/products/search`:
|
||||
|
||||
```bash apiTesting testApiUrl="http://localhost:9000/store/products/search" testApiMethod="POST" testBodyParams={{"q": "shirt"}}
|
||||
curl -X POST http://localhost:9000/store/products/search \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"q": "shirt"
|
||||
}'
|
||||
```
|
||||
|
||||
The response contains a `hits` array with the results from the MeiliSearch search engine.
|
||||
|
||||
### Add or Update Products
|
||||
|
||||
If you add or update products in your Medusa application, it'll be reflected in the MeiliSearch indices.
|
||||
|
||||
---
|
||||
|
||||
## Add Search to your Storefront
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- [MeiliSearch API key](https://www.meilisearch.com/docs/learn/security/master_api_keys#creating-an-api-key).
|
||||
|
||||
</Note>
|
||||
|
||||
### Next.js Starter
|
||||
|
||||
Refer to the [Next.js Starter guide](../../../nextjs-starter/page.mdx#configure-meilisearch) to learn how to configure MeiliSearch.
|
||||
|
||||
### Custom Storefront
|
||||
|
||||
To integrate MeiliSearch's search functionalities in your custom storefront, refer to [MeiliSearch's documentation](https://docs.meilisearch.com/learn/what_is_meilisearch/sdks.html#front-end-tools).
|
||||
Reference in New Issue
Block a user