MedusaWP

MedusaWP enables you to use WordPress as a headless CMS or as a storefront for your Medusa shop.

Features

• Use WordPress as a headless CMS or as a storefront for the Medusa shop.
• Connect to an existing Medusa store from WordPress and import its data into WordPress.
• Synchronize your Medusa e-commerce data with WordPress.
• Import Medusa thumbnails into the WordPress Media Library (either directly when syncing Medusa data or separately).
• Provide an overview and troubleshooting for the sync progress.
• Check the data health, including identifying any sync errors, partially synced items, or successfully synced data.
• Manage and display Medusa data (products, product collections...) in WordPress as custom post types (CPT).
• Automatically create a cart when the customer lands on the site for the first time (default country/region settings can be configured within the WordPress plugin settings).
• Implement a country switcher that updates the cart region based on the given country code.
• Remove all synced data.
• Disconnect from Medusa.
• Expose a rich set of functions available for you to use within your WordPress theme, including Copy to clipboardmedusa-react utility functions for computing and formatting prices and amounts.

Prerequisites

• Medusa Backend
• Redis
• WordPress Installation
  • WordPress website up and running
  • Administrator access to your WordPress website
• PHP Composer latest version 1.x

How To Install

Medusa Plugin

1. In the root of your Medusa backend, run the following command to install the Copy to clipboardmedusa-plugin-wordpress plugin:

1
npm i medusa-plugin-wordpress

2. Add the plugin to your Copy to clipboardmedusa-config.js file at the end of the Copy to clipboardplugins array:

12345678910111213
module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: "medusa-plugin-wordpress",
      options: {
        // ...
      },
    },
  ],
  // ...
}

3. Next, configure the Copy to clipboardmedusa-plugin-wordpress plugin that you added in the previous step. For example:

123456789101112131415
const plugins = [
  // ...
  {
    resolve: `medusa-plugin-wordpress`,
    options: {
      sync_options: {
        attempts: 5,
        backoff: {
          type: 'exponential',
          delay: 2000
        }
      }
    },
  },
]

Configuration Options

12345678
(property) sync_options: {
    delay?: number | undefined;
    attempts: number;
    backoff?: {
        type: "fixed" | "exponential";
        delay: number;
    } | undefined;
}

• Copy to clipboardsync_options
  • Sync options object.
    • Copy to clipboarddelay
      • Delay time in milliseconds, default Copy to clipboardundefined.
    • Copy to clipboardattempts
      • Number of attempts, default Copy to clipboard3.
    • Copy to clipboardbackoff
      • Backoff options object.
    • Copy to clipboardtype
      • Backoff type, either Copy to clipboard"fixed" or Copy to clipboard"exponential", default Copy to clipboard"exponential".
    • Copy to clipboarddelay
      • Backoff delay time in milliseconds, default Copy to clipboard2000.

WordPress Plugin

1. In the root directory of your WordPress installation, run the following command to install the plugin using Composer:

1
composer require agilo/medusawp

2. Log in to your WordPress admin dashboard using your administrator credentials.
3. After successful installation, click the "Activate" button to activate the plugin.
4. To finish the plugin setup, proceed to the How To Use steps.

How To Use

1. Run the following command in the directory of the Medusa backend to run the backend:

1
npm run start

2. After you have logged into your WordPress site, navigate to the MedusaWP plugin settings page, which can be found in the WordPress admin menu.
3. Connect your Medusa e-commerce store and your WordPress instance. On the default MedusaWP plugin screen enter your Medusa shop URL and credentials - email and password and press "Connect" button.

[!NOTE] If necessary, you can always disconnect from your Medusa shop by opening a dropdown in the upper-right corner, pressing the "Disconnect" button, and confirming your decision.

4. When the connection with Medusa is established, sync your Medusa e-commerce data with WordPress by clicking the "Sync" button. You can also choose to import Medusa thumbnails into the WordPress Media Library directly with the data sync (this may slightly slow down your data sync process), or you can import thumbnails separately later using the "Import" button.

[!NOTE] It is possible to remove all your synced Medusa data from your WordPress site at any time using the "Remove" button. We recommend that you backup your data before proceeding with this action.

5. Once the data synchronization is complete, configure the default settings of the MedusaWP plugin to suit your needs. In the dropdown, you can select the default country, which will be used to automatically create a cart in the corresponding region when a customer lands on the site.
6. Verify that the plugin is working as expected by visiting your website and using its features.

Contributing

Plugin Development

Prerequisites

• Docker and Docker Compose
  • We suggest using OrbStack on Mac.
• Node.js v20
  • We suggest using nvm or fnm to manage your Node.js versions.
• PHP Composer latest version 1.x | 2.x

1
127.0.0.1    medusawp.test

Running Locally

1. Fulfill everything mentioned in the prerequisites above
2. Copy to clipboardgit clone https://github.com/Agilo/medusawp.git
   • clone the repo
3. Copy to clipboardcd medusawp
   • position into the project directory
4. Copy to clipboardcp .env.example .env
   • set up docker-compose environment variables
5. Copy to clipboardcp ./dev/medusa/.env.example ./dev/medusa/.env
   • set up Medusa environment variables
6. Copy to clipboardnpm i
   • install all dependencies
7. Copy to clipboardnpm run addcert -w wordpress
   • add a self-signed certificate for Copy to clipboardmedusawp.test
8. Copy to clipboardnpm run build -w wordpress
   • build WordPress
9. Copy to clipboardcomposer install -d ./wordpress-plugin
   • install Composer dependencies for the WordPress plugin
10. Copy to clipboarddocker-compose --profile wp --profile medusa up
    • start WordPress and Medusa Docker containers
11. Open a new terminal tab
12. Copy to clipboardnpm run seed -w medusa
    • seed Medusa DB
13. Copy to clipboardnpm run migrate -w medusa
    • run Medusa migrations
14. Copy to clipboardnpm start
    • build the Medusa plugin and start the Medusa dev server and Medusa plugin watcher

12
admin@medusa-test.com
supersecret

12
admin
admin

Available Commands

• Copy to clipboardnpm start
  • build the plugin and start the Medusa dev server and plugin watcher
• Copy to clipboardnpm run build -w medusa-plugin-wordpress
  • build the Medusa plugin
• Copy to clipboardnpm run watch -w medusa-plugin-wordpress
  • start the Medusa plugin watcher
• Copy to clipboardnpm run test -w medusa-plugin-wordpress
  • run Medusa plugin tests
• Copy to clipboardnpm run seed -w medusa
  • seed Medusa DB
• Copy to clipboardnpm run build -w medusa
  • build Medusa
• Copy to clipboardnpm run migrate -w medusa
  • run Medusa migrations
• Copy to clipboardnpm start -w medusa
  • start the Medusa development server
• Copy to clipboardnpm run addcert -w wordpress
  • add a self-signed certificate for Copy to clipboardmedusawp.test
• Copy to clipboardnpm run build -w wordpress
  • build WordPress

Docker Services

• Copy to clipboardwp
  • WordPress
• Copy to clipboardmedusa
  • Medusa

WordPress

• Copy to clipboardnginx
  • Nginx web server that serves WordPress on https://medusawp.test
• Copy to clipboardphp
  • PHP-FPM
• Copy to clipboarddb
  • MariaDB database server for WordPress available on localhost:3306, you can change credentials and port in Copy to clipboard.env file
• Copy to clipboardphpmyadmin
  • phpMyAdmin available on http://localhost:8080

Medusa

• Copy to clipboardpostgres
  • PostgreSQL database server for Medusa available on localhost:5432, you can change credentials and port in Copy to clipboard.env and Copy to clipboarddev/medusa/.env files
• Copy to clipboardpgadmin
  • pgAdmin available on http://localhost:5050
• Copy to clipboardredis
  • Redis server for Medusa available on localhost:6379
• Copy to clipboardadmin
  • Medusa Admin available on http://localhost:9000

Additional Resources

• Medusa Documentation
• Medusa Development Documentation
• WordPress Documentation
• WordPress Developer Resources

License

Credits