Skip to main content

Contentful

In this document, you’ll learn how to integrate a Medusa server with Contentful to add rich Content Management System (CMS) functionalities

Overview

Contentful 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 account with a space created. A space is created by default when you create a new account.

Required Tools

Install Medusa Server Using Contentful Starter

Instead of using the default Medusa Server starter, you must use the Contentful starter to install a server that is ready to be used with Contentful. This server contains all the necessary files to make the integration work.

In your terminal, run the following command to install the server:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
medusa new medusa-contentful https://github.com/medusajs/medusa-starter-contentful
Copy to Clipboard

This installs a new Medusa server in the directory Copy to Clipboard.

Add Contentful Environment Variables

Change to the Copy to Clipboard directory. In Copy to Clipboard you’ll find three variables:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
CONTENTFUL_SPACE_ID=
CONTENTFUL_ACCESS_TOKEN=
CONTENTFUL_ENV=
Copy to Clipboard

Value of CONTENTFUL_ENV

Set the value for Copy to Clipboard to Copy to Clipboard.

Value of CONTENTFUL_SPACE_ID

To retrieve the value of Copy to Clipboard, go to your Contentful Space dashboard. Then, choose Settings in the navigation bar and select API keys from the dropdown.

Click on Settings then select API keys from the dropdown

On the APIs page, click Add API Key.

Click on the Add API Key button

In the form, enter a name for the API key and click Save.

A form with the name of API key entered

Then, copy the value of Space ID and set it as the value of Copy to Clipboard.

Value of CONTENTFUL_ACCESS_TOKEN

Go back to the API Keys page and click on the Content management tokens tab.

API Keys page with Content management tokens tab opened

Click on Generate personal token. A pop-up will open where you have to enter a name for the token.

Pop up model for Personal Access Token with token name entered

Once you click Generate, a personal access token will be generated. Use it to set the value of Copy to Clipboard.

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 Copy to Clipboard set the value of your Redis URL:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
REDIS_URL=<YOUR_REDIS_URL>
Copy to Clipboard

Where Copy to Clipboard is the URL of your Redis service.

The default Redis URL is Copy to Clipboard.

Configure PostgreSQL

In Copy to Clipboard set the value of your PostgreSQL URL:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
DATABASE_URL=<YOUR_DB_URL>
Copy to Clipboard

Where Copy to Clipboard is the URL of your PostgreSQL database.

You can find the format of the PostgreSQL database URL in PostgreSQL’s documentation.

Then, in Copy to Clipboard in the exported object, comment out or remove the SQLite database configurations and add the PostgreSQL database configurations:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
module.exports = {
projectConfig: {
//...
database_url: DATABASE_URL,
database_type: "postgres",
//REMOVE OR COMMENT OUT THE BELOW:
// database_database: "./medusa-db.sql",
// database_type: "sqlite",
},
};
Copy to Clipboard

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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm run migrate:contentful
Copy to Clipboard

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.

Content Model page filled with new content models

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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm run seed:contentful
Copy to Clipboard

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.

Content page filled with new content

(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 server.

Run the following command to seed the Medusa database:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm run seed
Copy to Clipboard

Start the Server

To start the server run the following command:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm run start
Copy to Clipboard

If you seeded the database with demo data, you should see that events related to the products are triggered.

Seed the database

The Contentful integration ensures a two-way sync between the Medusa server 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 server. 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 server 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.

Select all products' checkboxes and click the publish button

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.

Search for the featured products tile section

Click on it. You should find on the page an empty Tiles section where you can add tiles and products.

On the content's page find the empty tiles section

Click on Add content then on Add existing content and pick some of the products you want to show on the homepage.

Add at least 1 product as a tile

Once you’re done adding products, click on Publish changes in the right sidebar.

Click on the publish changes button on the right

Setup Gatsby Storefront

In this section, you’ll set up the Gatsby storefront of your Medusa server.

In your terminal in a different directory of the Medusa server, run the following command:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
gatsby new medusa-contentful-storefront https://github.com/medusajs/medusa-contentful-storefront
Copy to Clipboard

This will install the storefront in the directory Copy to Clipboard.

Set Contentful Environment Variables

Change to the newly created directory and rename Copy to Clipboard:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
mv .env.template .env
Copy to Clipboard

Then, open Copy to Clipboard. You should find the following environment variables:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
CONTENTFUL_SPACE_ID=
CONTENTFUL_ACCESS_TOKEN=
Copy to Clipboard

The value of Copy to Clipboard is the same value you retrieved while setting up the Medusa server.

To retrieve the value of Copy to Clipboard, 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 Copy to Clipboard.

Copy the value of the Content Delivery API access token

Start Storefront

Make sure the Medusa server is still running. Then, start the storefront:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
npm run start
Copy to Clipboard

This starts the storefront at Copy to Clipboard. Open it in your browser and you should see on the homepage the Featured Product section with the products you chose on Contentful.

The storefront with the featured products section

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.

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