Strapi
In this document, you’ll learn how to integrate Medusa with Strapi.
This plugin is a community plugin and is not managed by the official Medusa team. It supports v4 of Strapi. If you run into any issues, please refer to the repository of the community plugin.
Overview
Strapi 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 into Medusa, you can benefit from powerful features in your ecommerce store, including detailed product CMS details, two-way sync, an easy-to-use interface to use for static content and pages, and much more.
Prerequisites
Medusa Components
This guide assumes you already have a Medusa backend installed. If not, you can learn how to install it here.
An event bus module must be installed and configured on your Medusa backend to sync data from Medusa to Strapi. You can install the Redis event bus module.
Strapi Database
You must create a PostgreSQL database to be used with Strapi. You can refer to PostgreSQL’s documentation for more details.
Setup Strapi Project
In this section, you’ll setup a Strapi project with a Medusa plugin installed. To do that:
1. Clone the Strapi project repository:
2. Change to the medusa-strapi-repo/packages/medusa-strapi
directory.
3. Copy the .env.test
file to a new .env
file.
Change Strapi Environment Variables
In the .env
file, change the following environment variables:
# IMPORTANT: Change supersecret with random and unique strings
APP_KEYS=supersecret
API_TOKEN_SALT=supersecret
ADMIN_JWT_SECRET=supersecret
JWT_SECRET=supersecret
MEDUSA_STRAPI_SECRET=supersecret
MEDUSA_BACKEND_URL=http://localhost:9000
MEDUSA_BACKEND_ADMIN=http://localhost:7001
SUPERUSER_EMAIL=support@medusa-commerce.com
SUPERUSER_USERNAME=SuperUser
SUPERUSER_PASSWORD=MedusaStrapi1
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=postgres_strapi
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=
DATABASE_SSL=false
DATABASE_SCHEMA=public
- Change
APP_KEYS
,API_TOKEN_SALT
,JWT_SECRET
, andADMIN_JWT_SECRET
to a random and unique string. These keys are used by Strapi to sign session cookies, generate API tokens, and more. - Change
MEDUSA_STRAPI_SECRET
to a random unique string. The value of this environment variable is used later in your Medusa configurations. - Change
MEDUSA_BACKEND_URL
to the URL of your Medusa backend. If you’re running it locally, it should behttp://localhost:9000
. - Change
MEDUSA_BACKEND_ADMIN
to the URL of your Medusa Admin. If you’re running it locally, it should behttp://localhost:7001
. - Change the following environment variables to define the Strapi super user:
SUPERUSER_EMAIL
: the super user’s email. By default, it’ssupport@medusa-commerce.com
.SUPERUSER_USERNAME
: the super user’s username. By default, it’sSuperUser
.SUPERUSER_PASSWORD
: the super user’s password. By default, it’sMedusaStrapi1
.SUPERUSER_FIRSTNAME
: the super user’s first name. By default, it’sMedusa
.SUPERUSER_LASTNAME
: the super user’s last name. By default, it’sCommerce
.
- Change the database environment variables based on your database configurations. All database environment variables start with
DATABASE_
. - You can optionally configure other services, such as S3 or MeiliSearch, as explained here.
Build Packages
Once you’re done, install and build packages in the root medusa-strapi-repo
directory:
Install Plugin in Medusa
In the directory of your Medusa backend, run the following command to install the Strapi plugin:
Configure Plugin
Next, add the plugin to the plugins
array in medusa-config.js
:
const plugins = [
// ...
{
resolve: "medusa-plugin-strapi-ts",
options: {
strapi_protocol: process.env.STRAPI_PROTOCOL,
strapi_host: process.env.STRAPI_SERVER_HOSTNAME,
strapi_port: process.env.STRAPI_PORT,
strapi_secret: process.env.STRAPI_SECRET,
strapi_default_user: {
username: process.env.STRAPI_MEDUSA_USER,
password: process.env.STRAPI_MEDUSA_PASSWORD,
email: process.env.STRAPI_MEDUSA_EMAIL,
confirmed: true,
blocked: false,
provider: "local",
},
strapi_admin: {
username: process.env.STRAPI_SUPER_USERNAME,
password: process.env.STRAPI_SUPER_PASSWORD,
email: process.env.STRAPI_SUPER_USER_EMAIL,
},
auto_start: true,
},
},
]
The plugin accepts the following options:
strapi_protocol
: The protocol of the Strapi server. If running locally, it should behttp
. Otherwise, it should behttps
.strapi_host
: the domain of the Strapi server. If running locally, use127.0.0.1
.strapi_port
: the port that the Strapi server is running on, if any. If running locally, use1337
.strapi_secret
: the same secret used for theMEDUSA_STRAPI_SECRET
environment variable in the Strapi project.strapi_default_user
: The details of an existing user or a user to create in the Strapi backend that is used to update data in Strapi. It’s an object accepting the following properties:username
: The user’s username.password
: The user’s password.email
: The user’s email.confirmed
: Whether the user is confirmed.blocked
: Whether the user is blocked.provider
: The name of the authentication provider.
strapi_admin
: The details of the super admin. The super admin is only used to create the default user if it doesn’t exist. It’s an object accepting the following properties:username
: the super admin’s username. Its value is the same as that of theSUPERUSER_USERNAME
environment variable in the Strapi project.password
: the super admin’s password. Its value is the same as that of theSUPERUSER_PASSWORD
environment variable in the Strapi project.email
: the super admin’s email. Its value is the same as that of theSUPERUSER_EMAIL
environment variable in the Strapi project.
auto_start
: Whether to initialize the Strapi connection when Medusa starts. Disabling this may cause issues when syncing data from Medusa to Strapi.
Refer to the plugin’s README for more options.
Make sure to add the necessary environment variables for the above options in .env
:
STRAPI_PROTOCOL=http
STRAPI_SERVER_HOSTNAME=127.0.0.1
STRAPI_PORT=1337
STRAPI_SECRET=supersecret
STRAPI_MEDUSA_USER=medusa
STRAPI_MEDUSA_PASSWORD=supersecret
STRAPI_MEDUSA_EMAIL=admin@medusa-test.com
STRAPI_SUPER_USERNAME=SuperUser
STRAPI_SUPER_PASSWORD=MedusaStrapi1
STRAPI_SUPER_USER_EMAIL=support@medusa-commerce.com
Test Integration
To test the integration between Medusa and Strapi, first, start the Strapi server by running the following command in the medusa-strapi-repo/packages/medusa-strapi
directory:
Then, start the Medusa backend by running the following command in the root directory of your Medusa backend:
If the connection to Strapi is successful, you’ll find the following message logged in your Medusa backend with no errors:
Two-Way Syncing
To test syncing data from Medusa to Strapi, try creating or updating a product either using the Medusa Admin or the REST APIs. This triggers the associated event in Medusa, which makes the updates in Strapi.
If data isn’t synced with Strapi when making updates in Medusa, make sure that you’ve installed the event bus module as explained in the Prerequisites section and that the events are triggered.
To test syncing data from Strapi to Medusa, try updating one of the products in the Strapi dashboard. If you check the product’s details in Medusa, they’re updated as expected.
Data is only synced to Strapi once you create or update them. So, if you have products in your Medusa backend from before integrating Strapi, they won’t be available by default in Strapi. You’ll have to make updates to them, which triggers the update in Strapi.
Synced Entities
The Medusa and Strapi plugins support syncing the following Medusa entities:
Region
Product
ProductVariant
ProductCollection
ProductCategory
Learn More
To learn more about the integration between Medusa and Strapi, refer to the community plugin.