docs: publish restructure (#3496)
* docs: added features and guides overview page * added image * added version 2 * added version 3 * added version 4 * docs: implemented new color scheme * docs: redesigned sidebar (#3193) * docs: redesigned navbar for restructure (#3199) * docs: redesigned footer (#3209) * docs: redesigned cards (#3230) * docs: redesigned admonitions (#3231) * docs: redesign announcement bar (#3236) * docs: redesigned large cards (#3239) * docs: redesigned code blocks (#3253) * docs: redesigned search modal and page (#3264) * docs: redesigned doc footer (#3268) * docs: added new sidebars + refactored css and assets (#3279) * docs: redesigned api reference sidebar * docs: refactored css * docs: added code tabs transition * docs: added new sidebars * removed unused assets * remove unusued assets * Fix deploy errors * fix incorrect link * docs: fixed code responsivity + missing icons (#3283) * docs: changed icons (#3296) * docs: design fixes to the sidebar (#3297) * redesign fixes * docs: small design fixes * docs: several design fixes after restructure (#3299) * docs: bordered icon fixes * docs: desgin fixes * fixes to code blocks and sidebar scroll * design adjustments * docs: restructured homepage (#3305) * docs: restructured homepage * design fixes * fixed core concepts icon * docs: added core concepts page (#3318) * docs: restructured homepage * design fixes * docs: added core concepts page * changed text of different components * docs: added architecture link * added missing prop for user guide * docs: added regions overview page (#3327) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page (#3331) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page * fix link * resolve link issues * docs: updated regions architecture image * docs: second-iteration fixes (#3347) * docs: redesigned document * design fixes * docs: added products overview page (#3354) * docs: added carts overview page (#3363) * docs: added orders overview (#3364) * docs: added orders overview * added links in overview * docs: added vercel redirects * docs: added soon badge for cards (#3389) * docs: resolved feedback changes + organized troubleshooting pages (#3409) * docs: resolved feedback changes * added extra line * docs: changed icons for restructure (#3421) * docs: added taxes overview page (#3422) * docs: added taxes overview page * docs: fix sidebar label * added link to taxes overview page * fixed link * docs: fixed sidebar scroll (#3429) * docs: added discounts overview (#3432) * docs: added discounts overview * fixed links * docs: added gift cards overview (#3433) * docs: added price lists overview page (#3440) * docs: added price lists overview page * fixed links * docs: added sales channels overview page (#3441) * docs: added sales overview page * fixed links * docs: added users overview (#3443) * docs: fixed sidebar border height (#3444) * docs: fixed sidebar border height * fixed svg markup * docs: added possible solutions to feedback component (#3449) * docs: added several overview pages + restructured files (#3463) * docs: added several overview pages * fixed links * docs: added feature flags + PAK overview pages (#3464) * docs: added feature flags + PAK overview pages * fixed links * fix link * fix link * fixed links colors * docs: added strategies overview page (#3468) * docs: automated upgrade guide (#3470) * docs: automated upgrade guide * fixed vercel redirect * docs: restructured files in docs codebase (#3475) * docs: restructured files * docs: fixed eslint exception * docs: finished restructure loose-ends (#3493) * fixed uses of backend * docs: finished loose ends * eslint fixes * fixed links * merged master * added update instructions for v1.7.12
This commit is contained in:
Shahed Nasser
GitHub
349
docs/content/plugins/cms/contentful/customize-contentful.md
Normal file
349
docs/content/plugins/cms/contentful/customize-contentful.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
description: 'Learn how to customize the Contentful integration with Medusa and how to customize the Gatsby storefront that is connected to Contentful.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Customize your Medusa and Contentful Integration
|
||||
|
||||
In this document, you’ll learn how to customize the Contentful integration with Medusa and how to customize the Gatsby storefront that is connected to Contentful.
|
||||
|
||||
## Overview
|
||||
|
||||
Part of what makes the integration between Medusa and Contentful powerful is that it’s completely customizable.
|
||||
|
||||
On the backend, you can create Contentful migrations that allow you to add or edit Content Types in Contentful. Although this can be done through Contentful’s interface, this solution allows you to create a reusable codebase for your store that is independent of a specific Contentful Space.
|
||||
|
||||
On your storefront, you can add any necessary components that can render the Content Types you create.
|
||||
|
||||
As an example to explain this process, in this documentation, you’ll create a migration that creates a Rich Text content model in Contentful and edits the Page and Product content models to allow using Rich Text content as a tile in pages and products. Then, you’ll modify the Gatsby storefront to render the Rich Text content model.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
It’s assumed you already have set up a Medusa backend integrated with Contentful and have a Gatsby storefront integrated with Contentful. If not, [please follow this documentation first](index.md).
|
||||
|
||||
---
|
||||
|
||||
## Create a Contentful Migration
|
||||
|
||||
The Contentful migrations are located in the `contentful-migrations` directory in the Medusa Contentful backend starter. So, if you want to create your own Contentful migrations, you can create them under that directory.
|
||||
|
||||
Here’s an example of a migration created in a new file `contentful-migrations/rich-text.js`:
|
||||
|
||||
```jsx title=contentful-migrations/rich-text.js
|
||||
#! /usr/bin/env node
|
||||
|
||||
require("dotenv").config()
|
||||
|
||||
const { runMigration } = require("contentful-migration")
|
||||
|
||||
const options = {
|
||||
spaceId: process.env.CONTENTFUL_SPACE_ID,
|
||||
accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
|
||||
environment: process.env.CONTENTFUL_ENVIRONMENT,
|
||||
yes: true,
|
||||
}
|
||||
|
||||
const migration = async () => {
|
||||
await runMigration({
|
||||
...options,
|
||||
migrationFunction: function (migration, context) {
|
||||
|
||||
// create Rich Text content model
|
||||
const richText = migration
|
||||
.createContentType("richText")
|
||||
.name("Rich Text")
|
||||
.displayField("title")
|
||||
|
||||
richText
|
||||
.createField("title")
|
||||
.name("Title (Internal)")
|
||||
.type("Symbol")
|
||||
richText
|
||||
.createField("body")
|
||||
.name("Body")
|
||||
.type("RichText")
|
||||
|
||||
// edit Page content model
|
||||
const page = migration.editContentType("page")
|
||||
|
||||
page.editField("contentModules").items({
|
||||
type: "Link",
|
||||
linkType: "Entry",
|
||||
validations: [
|
||||
{
|
||||
linkContentType: [
|
||||
"hero", "tileSection", "richText",
|
||||
],
|
||||
},
|
||||
],
|
||||
})
|
||||
|
||||
// edit Product content model
|
||||
const product = migration.editContentType("product")
|
||||
|
||||
product
|
||||
.createField("contentModules")
|
||||
.name("Content Modules")
|
||||
.type("Array")
|
||||
.items({
|
||||
type: "Link",
|
||||
linkType: "Entry",
|
||||
validations: [
|
||||
{
|
||||
linkContentType: ["richText"],
|
||||
},
|
||||
],
|
||||
})
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
migration()
|
||||
```
|
||||
|
||||
This example creates a new content model Rich Text that has two fields: title and body. It also edits the Page content model to allow using Rich Text content models on the page.
|
||||
|
||||
In addition, it edits the Product content model by adding a new field `contentModules`. This field accepts an array of sections that can be of type Rich Text. This allows you to display rich details on a product page.
|
||||
|
||||
You can also add other types of content models the `contentModules` should accept. For example, to accept `tileSection` add it to the `linkContentType` option:
|
||||
|
||||
```jsx
|
||||
product
|
||||
.createField("contentModules")
|
||||
.name("Content Modules")
|
||||
.type("Array")
|
||||
.items({
|
||||
type: "Link",
|
||||
linkType: "Entry",
|
||||
validations: [
|
||||
{
|
||||
linkContentType: ["richText", "tileSection"],
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Run a Contentful Migration
|
||||
|
||||
To run a Contentful Migration that you create you can use the following command:
|
||||
|
||||
```bash
|
||||
node <file_path>
|
||||
```
|
||||
|
||||
Where `<file_path>` is the path of the file you created.
|
||||
|
||||
To run the Contentful migration in the previous example, you can use the following command:
|
||||
|
||||
```bash
|
||||
node contentful-migrations/rich-text.js
|
||||
```
|
||||
|
||||
This runs the Contentful migration in that file and makes the necessary changes in your Contentful Space.
|
||||
|
||||
### Test if Contentful Migration Worked
|
||||
|
||||
To check if the above migration worked, in your Contentful Space dashboard go to Content Models from the navigation bar. You should see the new content model Rich Text.
|
||||
|
||||
|
||||
|
||||
The above migration also allows you to add Rich Text content to pages. To test this out, go to Content from the navigation bar and choose Page in the select field next to the search bar. This shows the available pages in your Contentful Space.
|
||||
|
||||
|
||||
|
||||
Choose one of the pages. For example, the About page. Then, scroll down to the Add content button. If you click on it, you should be able to choose Rich Text under New Content.
|
||||
|
||||
|
||||
|
||||
Click on Rich Text and a new form will open to create new Rich Text content. It has the same fields that you defined in the migration file.
|
||||
|
||||
|
||||
|
||||
After adding the content you want, click on the Publish button on the right then go back to the About page editor.
|
||||
|
||||
|
||||
|
||||
Similarly, in the About page editor, click on the Publish Changes button on the right to view these changes later in the storefront.
|
||||
|
||||
|
||||
|
||||
Similarly, you can add Rich Text content to any product page.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Render New Content Models in the Storefront
|
||||
|
||||
After creating a new content model in your Contentful Space, you must add the necessary component to render it in your Gatsby storefront.
|
||||
|
||||
### Create Component
|
||||
|
||||
To render the Rich Text content you created in the previous example, create the file `src/components/rich-text/rich-text.js` with the following content:
|
||||
|
||||
```jsx title=src/components/rich-text/rich-text.js
|
||||
import React from "react"
|
||||
import {
|
||||
renderRichText,
|
||||
} from "gatsby-source-contentful/rich-text"
|
||||
|
||||
const RichText = ({ data }) => {
|
||||
return (
|
||||
<div style={{
|
||||
maxWidth: "870px",
|
||||
margin: "0 auto",
|
||||
paddingTop: "20px",
|
||||
paddingBottom: "20px",
|
||||
}}>
|
||||
{data.body ? renderRichText(data.body) : ""}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default RichText
|
||||
```
|
||||
|
||||
This creates the component `RichText` responsible for rendering the Rich Text content model. Notice that the fields of the content model are available under the `data` prop variable.
|
||||
|
||||
### Render Component in a Page
|
||||
|
||||
Since the Rich Text model can be added to any page, you must edit `src/pages/{ContentfulPage.slug}.js` to show it.
|
||||
|
||||
In `src/pages/{ContentfulPage.slug}.js`, import the `RichText` component at the top of the file:
|
||||
|
||||
```jsx title=src/pages/{ContentfulPage.slug}.js
|
||||
import RichText from "../components/rich-text/rich-text"
|
||||
```
|
||||
|
||||
Then, in the returned JSX add a new case to the switch statement:
|
||||
|
||||
```jsx title=src/pages/{ContentfulPage.slug}.js
|
||||
switch (cm.internal.type) {
|
||||
// ...
|
||||
case "ContentfulRichText":
|
||||
return <RichText key={cm.id} data={cm} />
|
||||
default:
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
If the content model of a tile is Rich Text, you’ll display it with the `RichText` component.
|
||||
|
||||
Finally, to retrieve all necessary data of the Rich Text content, in the `query` GraphQL variable add the following after the `... on ContentfulTileSection` fragment:
|
||||
|
||||
```jsx title=src/pages/{ContentfulPage.slug}.js
|
||||
export const query = graphql`
|
||||
# find the following line
|
||||
... on ContentfulTileSection {
|
||||
|
||||
}
|
||||
# add the following
|
||||
... on ContentfulRichText {
|
||||
id
|
||||
body {
|
||||
raw
|
||||
}
|
||||
internal {
|
||||
type
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`
|
||||
```
|
||||
|
||||
### Test Rich Text in Page Content
|
||||
|
||||
To test this out, run your Medusa backend by running this command in its directory:
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
Then run the Gatsby storefront by running this command in its directory:
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
This runs the Gatsby storefront on `localhost:8000`. Go to the storefront in your browser and open the About page. You should see the Rich Text content you added.
|
||||
|
||||
|
||||
|
||||
### Render Component in a Product Page
|
||||
|
||||
In the example migration, you also edited the product page to include a new Content Modules field that allows inserting Rich Text content.
|
||||
|
||||
To render them on the Product Page, add the following in the GraphQL query defined in the `query` variable inside `product`:
|
||||
|
||||
```jsx title=src/pages/{ContentfulPage.slug}.js
|
||||
export const query = graphql`
|
||||
query ($id: String!) {
|
||||
product: contentfulProduct(id: { eq: $id }) {
|
||||
# Other fields
|
||||
contentModules {
|
||||
... on ContentfulRichText {
|
||||
id
|
||||
body {
|
||||
raw
|
||||
}
|
||||
internal {
|
||||
type
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
`
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you added other accepted Content Models to the `contentModules` field of the Product content type, make sure to add them here.
|
||||
|
||||
:::
|
||||
|
||||
Then, in `src/views/product.js` import the `RichText` component:
|
||||
|
||||
```jsx title=src/views/product.js
|
||||
import RichText from "../components/rich-text/rich-text"
|
||||
```
|
||||
|
||||
And in the returned JSX add the following before the last `</div>`:
|
||||
|
||||
```jsx title=src/views/product.js
|
||||
<div className={styles.contentModules}>
|
||||
{product.contentModules?.map((cm) => {
|
||||
switch (cm.internal.type) {
|
||||
case "ContentfulRichText":
|
||||
return <RichText key={cm.id} data={cm} />
|
||||
default:
|
||||
return null
|
||||
}
|
||||
})}
|
||||
</div>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you added other accepted Content Models to the `contentModules` field of the Product content type, make sure to add cases for them here to display them.
|
||||
|
||||
:::
|
||||
|
||||
This loops over `contentModules` and if the type of the content is Rich Text, it is rendered with the `RichText` component.
|
||||
|
||||
### Test Rich Text on a Product Page
|
||||
|
||||
Restart the Gatsby storefront then open a product that you added Rich Text content to. You should see the Rich Text component at the end of the page.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md).
|
||||
- [How to deploy your Gatsby storefront to Netlify](../../../deployments/storefront/deploying-gatsby-on-netlify.md).
|
||||
303
docs/content/plugins/cms/contentful/index.md
Normal file
303
docs/content/plugins/cms/contentful/index.md
Normal file
@@ -0,0 +1,303 @@
|
||||
---
|
||||
description: 'Learn how to integrate Contentful with the Medusa backend and a Gatsby storefront. Contentful is a headless CMS backend that provides rich CMS functionalities.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Contentful
|
||||
|
||||
In this document, you’ll learn how to integrate a Medusa backend with Contentful to add rich Content Management System (CMS) functionalities
|
||||
|
||||
## Overview
|
||||
|
||||
[Contentful](https://www.contentful.com/) is a headless CMS service that allows developers to integrate rich CMS functionalities into any platform.
|
||||
|
||||
By integrating Contentful to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, easy-to-use interface to use for static content and pages, localization, and much more.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- [Contentful](https://www.contentful.com/sign-up/) account with a space created. A space is created by default when you create a new account.
|
||||
|
||||
### 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).
|
||||
- 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).
|
||||
|
||||
---
|
||||
|
||||
## Install Medusa Backend Using Contentful Starter
|
||||
|
||||
Instead of using the default Medusa backend starter, you must use the [Contentful starter](https://github.com/medusajs/medusa-starter-contentful) to install a backend that is ready to be used with Contentful. This backend contains all the necessary files to make the integration work.
|
||||
|
||||
In your terminal, run the following command to install the backend:
|
||||
|
||||
```bash
|
||||
medusa new medusa-contentful https://github.com/medusajs/medusa-starter-contentful
|
||||
```
|
||||
|
||||
This installs a new Medusa backend in the directory `medusa-contentful`.
|
||||
|
||||
### Add Contentful Environment Variables
|
||||
|
||||
Change to the `medusa-contentful` directory. In `.env` you’ll find three variables:
|
||||
|
||||
```bash title=.env
|
||||
CONTENTFUL_SPACE_ID=
|
||||
CONTENTFUL_ACCESS_TOKEN=
|
||||
CONTENTFUL_ENV=
|
||||
```
|
||||
|
||||
#### Value of CONTENTFUL_ENV
|
||||
|
||||
Set the value for `CONTENTFUL_ENV` to `master`.
|
||||
|
||||
#### Value of CONTENTFUL_SPACE_ID
|
||||
|
||||
To retrieve the value of `CONTENTFUL_SPACE_ID`, go to your [Contentful Space dashboard](https://app.contentful.com/). Then, choose Settings in the navigation bar and select API keys from the dropdown.
|
||||
|
||||
|
||||
|
||||
On the APIs page, click Add API Key.
|
||||
|
||||
|
||||
|
||||
In the form, enter a name for the API key and click Save.
|
||||
|
||||
|
||||
|
||||
Then, copy the value of Space ID and set it as the value of `CONTENTFUL_SPACE_ID`.
|
||||
|
||||
#### Value of CONTENTFUL_ACCESS_TOKEN
|
||||
|
||||
Go back to the API Keys page and click on the Content management tokens tab.
|
||||
|
||||
|
||||
|
||||
Click on Generate personal token. A pop-up will open where you have to enter a name for the token.
|
||||
|
||||
|
||||
|
||||
Once you click Generate, a personal access token will be generated. Use it to set the value of `CONTENTFUL_ACCESS_TOKEN`.
|
||||
|
||||
:::warning
|
||||
|
||||
Once you close the pop-up, you won’t be able to get the value of the personal access token again. Make sure to copy it first.
|
||||
|
||||
:::
|
||||
|
||||
### Configure Redis
|
||||
|
||||
In `.env` set the value of your Redis URL:
|
||||
|
||||
```bash
|
||||
REDIS_URL=<YOUR_REDIS_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_REDIS_URL>` is the URL of your Redis service.
|
||||
|
||||
:::tip
|
||||
|
||||
The default Redis URL is `redis://localhost:6379`.
|
||||
|
||||
:::
|
||||
|
||||
### Configure PostgreSQL
|
||||
|
||||
In `.env` set the value of your PostgreSQL URL:
|
||||
|
||||
```bash
|
||||
DATABASE_URL=<YOUR_DB_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_DB_URL>` is the URL of your PostgreSQL database.
|
||||
|
||||
:::tip
|
||||
|
||||
You can find the format of the PostgreSQL database URL in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
|
||||
|
||||
:::
|
||||
|
||||
Then, in `medusa-config.js` in the exported object, comment out or remove the SQLite database configurations and add the PostgreSQL database configurations:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
database_url: DATABASE_URL,
|
||||
database_type: "postgres",
|
||||
// REMOVE OR COMMENT OUT THE BELOW:
|
||||
// database_database: "./medusa-db.sql",
|
||||
// database_type: "sqlite",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Migrate Content Types to Contentful
|
||||
|
||||
The Contentful starter provides the necessary scripts to create content types in your Contentful space.
|
||||
|
||||
Run the following commands to migrate the content types into Contentful:
|
||||
|
||||
```bash
|
||||
npm run migrate:contentful
|
||||
```
|
||||
|
||||
Once this command finishes executing, in your Contentful Space dashboard click on Content Model in the navigation bar. You should see a list of new content models added.
|
||||
|
||||
|
||||
|
||||
### Seed Content to Contentful
|
||||
|
||||
The next step is to seed the Contentful Space with some content data.
|
||||
|
||||
Run the following command to seed some data into it:
|
||||
|
||||
```bash
|
||||
npm run seed:contentful
|
||||
```
|
||||
|
||||
After this command finishes running, in your Contentful Space dashboard click on Content in the navigation bar. You should see a list of new content added.
|
||||
|
||||
|
||||
|
||||
### (Optional) Seed Medusa Database
|
||||
|
||||
This step seeds your Medusa database with demo data to easily add products as well as other data to your Medusa backend.
|
||||
|
||||
Run the following command to seed the Medusa database:
|
||||
|
||||
```bash
|
||||
npm run seed
|
||||
```
|
||||
|
||||
### Start the Backend
|
||||
|
||||
To start the backend run the following command:
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
If you seeded the database with demo data, you should see that events related to the products are triggered.
|
||||
|
||||
|
||||
|
||||
The Contentful integration ensures a two-way sync between the Medusa backend and Contentful. So, when new products are added to Medusa, these products will be added to your Contentful Space as well.
|
||||
|
||||
---
|
||||
|
||||
## (Optional) Add Products with the Medusa Admin
|
||||
|
||||
Using the Medusa admin, you can add products to your Medusa backend. This will trigger product events that subsequently add these products to Contentful.
|
||||
|
||||
---
|
||||
|
||||
## Manage Contentful Data
|
||||
|
||||
### Publish Products
|
||||
|
||||
Products added through the integration with the Medusa backend are by default saved as drafts. To show them on the storefront, you must set them as published.
|
||||
|
||||
To do that, open your Contentful Space Dashboard and click on Content in the Navigation bar. Then, change Any to Product in the select field next to the search bar. This shows only the content of the type Product, rather than all content.
|
||||
|
||||
Click on the checkbox at the top of the table to select all products then click Publish to publish these products.
|
||||
|
||||
|
||||
|
||||
### Added Featured Products
|
||||
|
||||
On the homepage of the storefront, there’s a featured products tile that shows a set of products. Before running the storefront, you must add at least one product to the list.
|
||||
|
||||
To do that, open your Contentful Space Dashboard and click on Content in the Navigation bar. Make sure the select field next to the search bar is set to Any and search for Featured Products. You should find one content of the type Tile Section.
|
||||
|
||||
|
||||
|
||||
Click on it. You should find on the page an empty Tiles section where you can add tiles and products.
|
||||
|
||||
|
||||
|
||||
Click on Add content then on Add existing content and pick some of the products you want to show on the homepage.
|
||||
|
||||
|
||||
|
||||
Once you’re done adding products, click on Publish changes in the right sidebar.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Setup Gatsby Storefront
|
||||
|
||||
In this section, you’ll set up the Gatsby storefront of your Medusa backend.
|
||||
|
||||
In your terminal in a different directory of the Medusa backend, run the following command:
|
||||
|
||||
```bash
|
||||
gatsby new medusa-contentful-storefront https://github.com/medusajs/medusa-contentful-storefront
|
||||
```
|
||||
|
||||
This will install the storefront in the directory `medusa-contentful-storefront`.
|
||||
|
||||
### Set Contentful Environment Variables
|
||||
|
||||
Change to the newly created directory and rename `.env.template`:
|
||||
|
||||
```bash
|
||||
mv .env.template .env
|
||||
```
|
||||
|
||||
Then, open `.env`. You should find the following environment variables:
|
||||
|
||||
```bash title=.env
|
||||
CONTENTFUL_SPACE_ID=
|
||||
CONTENTFUL_ACCESS_TOKEN=
|
||||
```
|
||||
|
||||
The value of `CONTENTFUL_SPACE_ID` is the same value you [retrieved while setting up the Medusa backend](#value-of-contentful_space_id).
|
||||
|
||||
To retrieve the value of `CONTENTFUL_ACCESS_TOKEN`, on your Contentful Space dashboard click on Settings then API keys. Then, choose the API key you created in the previous section.
|
||||
|
||||
You should find the field "Content Delivery API - access token”. Copy its value and set it as the value of `CONTENTFUL_ACCESS_TOKEN`.
|
||||
|
||||
|
||||
|
||||
### Start Storefront
|
||||
|
||||
Make sure the Medusa backend is still running. Then, start the storefront:
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
This starts the storefront at `localhost:8000`. Open it in your browser and you should see on the homepage the Featured Product section with the products you chose on Contentful.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Make Changes to Content
|
||||
|
||||
You can update the CMS content of your storefront in your Contentful Space. This includes the CMS pages or product details.
|
||||
|
||||
:::note
|
||||
|
||||
If you make changes to the data while your Gatsby storefront is running, the changes are not reflected instantly. That’s because the data is fetched from Contentful during build time. Instead, you must restart your Gatsby storefront to see the changes you make.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## What’s Next
|
||||
|
||||
Learn [How to customize your Contentful backend and storefront](./customize-contentful.md).
|
||||
|
||||
## See Also
|
||||
|
||||
- How to deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md).
|
||||
- [How to deploy your Gatsby storefront to Netlify](../../../deployments/storefront/deploying-gatsby-on-netlify.md).
|
||||
5
docs/content/plugins/cms/index.mdx
Normal file
5
docs/content/plugins/cms/index.mdx
Normal file
@@ -0,0 +1,5 @@
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
# CMS Plugins
|
||||
|
||||
<DocCardList />
|
||||
199
docs/content/plugins/cms/strapi.md
Normal file
199
docs/content/plugins/cms/strapi.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
description: 'Learn how to integrate Strapi with the Medusa backend. Learn how to install the plugin and test two-way sync between the ecommerce and CMS services.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Strapi
|
||||
|
||||
In this document, you’ll learn how to integrate Strapi with Medusa to add rich Content Management System (CMS) functionalities.
|
||||
|
||||
:::info
|
||||
|
||||
This plugin is a [community plugin](https://github.com/Deathwish98/medusa-plugin-strapi) and is not managed by the official Medusa team. At the moment, it supports v4 of Strapi.
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
[Strapi](https://strapi.io/) is an open source headless CMS service that allows developers to have complete control over their content models. It can be integrated into many other frameworks, including Medusa.
|
||||
|
||||
By integrating Strapi to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, [two-way sync](#test-two-way-sync), an easy-to-use interface to use for static content and pages, and much more.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa CLI
|
||||
|
||||
[Medusa’s CLI tool](../../cli/reference.md#how-to-install-cli-tool) is required to set up a new Medusa backend.
|
||||
|
||||
### Redis
|
||||
|
||||
Redis is required for the Strapi plugin to work as expected on your Medusa backend. If you don’t have it installed, you can learn [how to install it in this documentation](../../development/backend/prepare-environment.mdx#redis).
|
||||
|
||||
---
|
||||
|
||||
## Create Strapi Project
|
||||
|
||||
The first step is to create a Strapi project using the Medusa template:
|
||||
|
||||
```bash
|
||||
npx create-strapi-app strapi-medusa --template shahednasser/strapi-medusa-template
|
||||
```
|
||||
|
||||
This creates the Strapi project in the directory `strapi-medusa`.
|
||||
|
||||
Once the installation is finished, the Strapi development backend will run on `localhost:1337`. A new page will also open in your default browser to create a new admin user and log in.
|
||||
|
||||
|
||||
|
||||
Once you log in, you can access the Strapi dashboard.
|
||||
|
||||
### Create a Strapi User
|
||||
|
||||
The Strapi plugin in Medusa requires the credentials of a Strapi user. To create a new user, go to Content Manager, then choose User under Collection Types.
|
||||
|
||||
|
||||
|
||||
Click on the Create new entry button at the top right. This opens a new form to enter the user’s details.
|
||||
|
||||
|
||||
|
||||
Enter the user’s username, email, and password. Once you’re done, click on the Save button at the top right.
|
||||
|
||||
---
|
||||
|
||||
## Modify Permissions
|
||||
|
||||
By default, created users have the “Authenticated” role. Before you start using the Strapi plugin on your Medusa backend, you must modify this role’s permissions to allow making changes to Medusa’s models in Strapi.
|
||||
|
||||
On your Strapi dashboard, go to Settings → Roles → Authenticated. Then, under the Permissions section, expand the accordion of each content model type and check the Select All checkbox.
|
||||
|
||||
|
||||
|
||||
Once you’re done, click the Save button at the top right.
|
||||
|
||||
---
|
||||
|
||||
## Create Medusa Backend
|
||||
|
||||
:::note
|
||||
|
||||
You can use the Strapi plugin on an existing Medusa backend, however, existing data (such as existing products) will not be imported. Only newer data will be imported.
|
||||
|
||||
:::
|
||||
|
||||
To create your Medusa backend, run the following command:
|
||||
|
||||
```bash
|
||||
medusa new medusa-backend --seed
|
||||
```
|
||||
|
||||
The `--seed` flag creates an SQLite database and seeds it with some demo data.
|
||||
|
||||
### Configure your Backend
|
||||
|
||||
Once the command is done executing, change to the newly created `medusa-backend` directory. Then, in `medusa-config.js`, change the exported object at the end of the file to enable Redis:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
redis_url: REDIS_URL,
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
This uses the default Redis configurations. If you want to learn more about configuring Redis, [check out this documentation](../../development/backend/configurations.md#redis).
|
||||
|
||||
:::tip
|
||||
|
||||
It is also recommended to use PostgreSQL for an optimal experience, however, it is not required. Learn how to [install](../../development/backend/prepare-environment.mdx#postgres) and [configure](../../development/backend/configurations.md#postgresql-configurations) it on your Medusa backend.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Install the Strapi Plugin
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install the Strapi plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-strapi
|
||||
```
|
||||
|
||||
Then, add the following environment variables:
|
||||
|
||||
```bash
|
||||
STRAPI_USER=<STRAPI_IDENTIFIER>
|
||||
STRAPI_PASSWORD=<STRAPI_PASSWORD>
|
||||
STRAPI_PROTOCOL=http # Optional
|
||||
STRAPI_URL=<STRAPI_URL> # Optional
|
||||
STRAPI_PORT=<STRAPI_PORT> # Optional
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<STRAPI_IDENTIFIER>` is either the email address or username of the user you created in the previous step.
|
||||
- `<STRAPI_PASSWORD>` is the password of the user you created in the previous step.
|
||||
- `<STRAPI_PROTOCOL>` is the protocol of your Strapi backend. If you’re using a local Strapi backend, set this to `http`. The default value is `https`.
|
||||
- `<STRAPI_URL>` is the URL of your Strapi backend. By default, the URL is `localhost`.
|
||||
- `<STRAPI_PORT>` is the port the Strapi backend runs on. By default, the port is `1337`.
|
||||
|
||||
Finally, open `medusa-config.js` and add the following new item to the `plugins` array:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-strapi`,
|
||||
options: {
|
||||
strapi_medusa_user: process.env.STRAPI_USER,
|
||||
strapi_medusa_password: process.env.STRAPI_PASSWORD,
|
||||
strapi_url: process.env.STRAPI_URL, // optional
|
||||
strapi_port: process.env.STRAPI_PORT, // optional
|
||||
strapi_protocol: process.env.STRAPI_PROTOCOL, // optional
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Run Medusa Backend
|
||||
|
||||
Make sure the Strapi backend is still running. If not, you can run the following command to run the Strapi backend in the directory of the Strapi project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run develop
|
||||
```
|
||||
|
||||
Then, in the directory of your Medusa backend, run the following command to start the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run start
|
||||
```
|
||||
|
||||
Once you start your Medusa backend, if you ran the `--seed` command when you created your Medusa backend, you’ll see that `product.created` events have been triggered along with similar events. This will update Strapi with the products you seeded.
|
||||
|
||||
---
|
||||
|
||||
## Test Two-Way Sync
|
||||
|
||||
This plugin ensures a two-way sync between the Medusa backend and the Strapi backend. So, if you update data on Strapi, it will be reflected on your Medusa backend, and vice-versa.
|
||||
|
||||
### Update Products on Strapi
|
||||
|
||||
Try updating any products on Strapi by going to Content Manager → Products and choosing a product from the list. Then, make changes to the product and click Save. If you view the products on your backend now, either using the [REST APIs](/api/admin/#tag/Product/operation/GetProducts) or using [the Medusa Admin](../../user-guide/products/index.mdx), you’ll see that the product has been updated.
|
||||
|
||||
### Update Products on Medusa
|
||||
|
||||
If you try to update products on Medusa either using the [REST APIs](/api/admin/#tag/Product/operation/PostProductsProduct) or using [the Medusa Admin](../../user-guide/products/manage.mdx), you’ll see that the product is also updated on Strapi.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy the Medusa backend](../../deployments/server/index.mdx)
|
||||
- [Create your own plugin](../../development/plugins/create.md)
|
||||
Reference in New Issue
Block a user