
A quick guide by our CTO, Oliver, on how to deploy your [Medusa](https://www.medusajs.com/) ecommerce backend to Heroku.

> We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to quickly set up your application. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a short walkthrough.

After this tutorial, you will have a live headless commerce backend to start your ecommerce store from.

{% embed https://www.youtube.com/watch?v=nqZKnkrGMA0&ab_ %}

---

**For the written tutorial:** [https://docs.medusajs.com/how-to/deploying-on-heroku/](https://docs.medusajs.com/how-to/deploying-on-heroku/)

Should you have any problems setting this up, then feel free to hit us up on our [Discord](https://discord.com/invite/medusajs).

Hope you found the tutorial helpful!


Video: Deploy your Medusa store on Heroku in 5 minutes

<p class="text-regular font-medium text-theme-text-primary">
  Try Medusa
</p>
<p class="text-regular text-theme-text-secondary">
  Spin up your environment in a few minutes.
</p>



Grid

Good Chef & Webbers: Powering subscriptions with Medusa’s commerce modules


[Webbers Agency](https://webbers.com/) helped build an online meal subscription store for [Good Chef](https://goodchef.nl/) that sells shock frozen plant-based food. Webbers chose Medusa for its building blocks, which provided them with the flexibility to support Good Chef’s subscription logic while giving customers a great online experience.

<video controls preload="none" style="object-fit: cover;" poster="/images/goodchef-video-cover.png">
<source src="/videos/goodchef-video.mp4" type="video/mp4" />
</video>

## Ideal solution for a bespoke subscription model

When scoping the Good Chef project, Webbers identified that the subscription logic would be a key constraint on the implementation. Other ecommerce platforms were too rigid to support Good Chef's subscriptions, and the alternative of building the entire system from scratch would mean spending a lot of time recreating core commerce features like cart logic and discounts.

Instead, they chose to use Medusa, which provides building blocks for core commerce logic that can easily be customized for custom needs, like Good Chef's subscriptions.

> “We had used Magento and WooCommerce in the past, but they were not ideal for a modern headless stack. We tested Shopify, but then quickly hit a limit on how scalable and customizable the setup could be.” — Daan van den Burg, Managing Partner at Webbers Agency.

It was important for Good Chef that subscriptions could be paid with the customer's preferred payment method. Likewise, they wanted the subscription flow, e.g. when renewals should happen, to be controllable as part of the commerce logic. This meant that Webbers couldn't use a payment provider-specific subscription solution like Stripe Billing.

So, they decided to build the subscription logic into Good Chef's Medusa project, making it independent of payment providers and giving customers the best experience.

## Building Subscription into Medusa

It is possible for customers to make single purchases on the site, but for the most part, customers sign up via the subscription flow outlined below.

![](/images/goodchef-customer-journey-2_(3\).png)

To implement subscriptions, Webbers leveraged Medusa's support for [custom data models](https://docs.medusajs.com/development/entities/overview). Webbers created a Subscription data model to hold information about Good Chef's offerings, including type of meal box, available frequencies and prices. Additionally, they added relations between Orders and Subscriptions to be able to track which Subscription an Order is related to.

> “The architecture of Medusa made it simple to add custom logic to the codebase. It was very easy to create our own entities and extend Orders in Medusa.” — Pepijn van Vlaanderen, Head of Development at Webbers

To trigger the creation of new Orders, Webbers used [Medusa's cron jobs](https://docs.medusajs.com/development/scheduled-jobs/overview) to execute a nightly check for Subscriptions that need renewal. Orders are created with Line Items of the customer's chosen meal box and are automatically paid for through the Subscription payment method.

![](/images/goodchef_payment_flow_-_vertical_(2\).jpg)

With this implementation, Webbers was able to bring Good Chef’s vision to life without compromising the commerce system’s flexibility or their control over the logic behind the subscription flow.

## Straightforward Developer Experience

This project was Webbers’ first time using Medusa, so they had to learn its architecture and fundamentals to understand how to customize it and implement Good Chef’s use case. This was not a big challenge, and they quickly grasped the concepts within Medusa and how to utilize them.

> “It was a new system for us, but it was straightforward and easy to learn.” — Pepijn van Vlaanderen

One of the aspects the Webbers team has come to appreciate is the developer experience that Medusa provides. It offers the flexibility to select only the necessary functionality for their use case and extend with custom logic when needed.

This made Medusa the commerce infrastructure of choice for Webbers, as they now use it as their go-to solution in other client projects.

> “We like the SDK approach that Medusa offers, as it makes it easy for us to cherry-pick what we need and quickly build it out. It gave us the confidence to use Medusa for other projects so that we can help our clients and give them a stable ecommerce infrastructure.” — Pepijn van Vlaanderen



Community Highlights: Strapi Integration, SES Plugin, and More!

[Changing the way commerce is built](https://medusajs.com/readme/) is no easy undertaking. Therefore, we are incredibly excited about our Medusa community, their support, and their amazing contributions that make it easier for others to move to a more modular way of building commerce.

This article is part of an ongoing series that periodically highlights community plugins, storefront starters, quotes, and more. Join our community of over 5,000 developers on [Discord](https://discord.com/invite/medusajs) to stay updated with all community-related news and discussions. You can also visit our [Plugin Library](https://medusajs.com/plugins/) to browse many community contributions.

## Latest community contributions

### Medusa and Strapi Integration

![](/images/ou83fyNmjX.png)

[Govind Diwakar](https://github.com/SGFGOV) has created a [Strapi monorepository](https://github.com/SGFGOV/medusa-strapi-repo) with all the components necessary for you to set up and use Strapi with Medusa. Within this monorepository, you’ll find a Strapi project, a Medusa plugin for Strapi, a Strapi plugin for Medusa, and other components that will make your integration between Medusa and Strapi successful.

By integrating Strapi and Medusa, you can utilize rich CMS features that Strapi provides while using Medusa’s powerful commerce features.

Check out the [monorepository](https://github.com/SGFGOV/medusa-strapi-repo) for more details about the project and how to set it up.

### Medusa SES Plugin

[Lacey Pevey](https://github.com/pevey) created a plugin that allows you to use AWS Simple Email Service (SES) as a notification provider in your Medusa backend. By using this plugin, you can send emails to the customer when an order is placed, a password reset has been requested, a gift card has been created, and more using AWS SES.

The templates used for the emails are stored within your Medusa backend in a `data` directory, and they’re based on handlebars. So, they’re compatible with SendGrid templates as well.

Check out the [Medusa SES Plugin](https://medusajs.com/plugins/medusa-plugin-ses/) for more details about its features and how to install it.

### Medusa SvelteKit Client

We also got a much-requested SvelteKit client that lets you interact with your Medusa backend from a SvelteKit storefront. With this client, you can easily build a SvelteKit storefront or admin for your Medusa backend.

SvelteKit enables you to combine the fluid user experience of client-side reactivity with the ability to handle logic on the server when desired. This keeps your Medusa backend firewall-protected and accessible only to your storefront server, which provides an additional layer of security compared to directly exposing your backend.

Check out the [Medusa SvelteKit Client](https://medusajs.com/plugins/sveltekit-medusa-client/) for more details about its features and how to install it. Thanks to [Lacey Pevey](https://github.com/pevey) for another great contribution.

## Community Radar

<tweet tweetId="1650797861192323072" />

## Created something cool with Medusa? Let us know!

We would love to hear about all the cool projects you’ve created with Medusa. Whether it’s plugins, storefront starters, your own store built with Medusa, or anything similar, we’d love to see it and hopefully share it in our next Community Highlights!

You can share all your cool projects in the Showcase channel on our [Discord](https://discord.com/invite/medusajs). You can also learn how to publish your plugins on our Plugin Library using this guide in our [documentation](https://docs.medusajs.com/development/plugins/publish).


Announcing Medusa's Community Publication

At Medusa, we’re introducing our new community publication, [Medusa Community](https://medusa-community.hashnode.dev/welcome-to-medusas-community-publication), hosted on Hashnode. This publication gives writers interested in writing about Medusa a platform where they can be recognized and paid for their work.

Keep reading below to learn more about this publication and how you can join!

## Why create a community publication?

Last year, we created a Writers Program at Medusa, where we were able to work with over 200 writers in producing content related to Medusa. This has allowed us to create diverse content of different types and levels based on the different skills the community writers provided.

As the Writers Program continued to grow and gain interest, we realized how important it is to highlight the community’s work and make it easier for more people to contribute and join. The community publication aims to solve a lot of the limitations we had with the Writers Program, while also providing creative and useful content for the community, by the community.

## How does it work?

We share all the details about the new publication in our new [Write for Us page](https://medusajs.notion.site/Write-for-us-74a2bf43b4ce43eeba200382f599321a). To sum it up:

*   You can join as a writer using [this form](https://ky5eo2x1u81.typeform.com/to/J6lDIwtJ).
*   You’ll then receive an email with the details to join the Hashnode publication and any other necessary resources.
*   That’s it! You can then start writing and submitting content to the community publication.

### Important notes

*   It’s important to sign up again as a writer using the form mentioned above, even if you were previously part of the Writers Program.
*   Your article must match our [writing guidelines](/8f3be54b95654fe8bfbb45503e7eed8a).
*   Articles are not instantly published on the publication, as we might specify a schedule on how and when we decide to post the article.
*   You’ll receive payment if your article is published or scheduled.
*   Although you can generally write about anything related to Medusa, we also have guidelines on what topics we are against and some things to keep in mind when writing. You can learn more [here](/8f3be54b95654fe8bfbb45503e7eed8a).

## Benefits of joining the Community Publication

*   Your content will be recognized by the Medusa community. We’ll also often share articles we find insightful or creative across our channels.
*   You’ll get paid for your work. We also offer bonus payments if your article gets featured on Hashnode or other publications.

## Start writing for Medusa

Interested in the Community Publication? You can join the publication through [this form](https://ky5eo2x1u81.typeform.com/to/J6lDIwtJ).

Check out the Medusa Community Publication and follow it on Hashnode to stay updated with all community content.


Announcing Medusa’s Community Publication

At Medusa, we empower developers to do more with less. Our modular approach to commerce tooling equips developers with the means to create rich applications without hacky workarounds.

These applications often integrate with 3rd party solutions e.g. to accept payments, which we support through easy-to-configure plugins. To make our plugins more conveniently accessible, we are excited to have recently launched our Plugin Library.

Our [Medusa Plugin Library](https://medusajs.com/plugins/) provides a simple way to view the pre-built plugins available for Medusa. The list includes plugins supported by the core team (indicated by a small Medusa logo) and community plugins that can be accessed through npm.

## Covering the full commerce stack

By using Medusa commerce modules, you already get a strong commerce foundation out of the box, including support of [inventory and multi-warehousing](https://docs.medusajs.com/modules/multiwarehouse/overview), [multi-region support](https://docs.medusajs.com/modules/regions-and-currencies/overview), [multi-channel handling](https://docs.medusajs.com/modules/sales-channels/overview), [advanced tax](https://docs.medusajs.com/modules/taxes/overview), [promotion features](https://docs.medusajs.com/modules/price-lists/overview), and more.

Our Plugin Library allows you to extend beyond these modules and quickly build a connected stack with integrations for services such as:

*   **Payments** (e.g. [Stripe](https://medusajs.com/plugins/medusa-payment-stripe/), [Paypal](https://medusajs.com/plugins/medusa-payment-paypal/), [Adyen](https://medusajs.com/plugins/medusa-payment-adyen/), [Klarna](https://medusajs.com/plugins/medusa-payment-klarna/))
*   **Notifications** (e.g. [Sendgrid](https://medusajs.com/plugins/medusa-plugin-sendgrid/), [Mailchimp](https://medusajs.com/plugins/medusa-plugin-mailchimp/), [Slack](https://medusajs.com/plugins/medusa-plugin-slack-notification/), [Twilio](https://medusajs.com/plugins/medusa-plugin-twilio-sms/))
*   **Shipping** (e.g. [Webshipper](https://medusajs.com/plugins/medusa-fulfillment-webshipper/), [Brightpearl](https://medusajs.com/plugins/medusa-plugin-brightpearl/), [Shippo](https://medusajs.com/plugins/medusa-fulfillment-shippo/))
*   **Search** (e.g. [MeiliSearch](https://medusajs.com/plugins/medusa-plugin-meilisearch/), [Algolia](https://medusajs.com/plugins/medusa-plugin-algolia/))
*   **Storage** (e.g. [S3](https://medusajs.com/plugins/medusa-file-s3/), [DigitalOcean](https://medusajs.com/plugins/medusa-file-spaces/), [MinIO](https://medusajs.com/plugins/medusa-file-minio/))
*   **CMS** (e.g. [Contentful](https://medusajs.com/plugins/medusa-plugin-contentful/))
*   **Analytics and monitoring** (e.g. [Segment](https://medusajs.com/plugins/medusa-plugin-segment/), [Sentry](https://medusajs.com/plugins/medusa-plugin-sentry/))

## Contributing your own plugin

We always welcome community contributions. To get your plugin live in our Plugin Library, all you have to do is [create your own Medusa plugi](https://docs.medusajs.com/development/plugins/create)n and publish it through npm following our [publishing guidelines](https://docs.medusajs.com/development/plugins/publish). Within a week the plugin will appear in the plugin library. If this is not the case, feel free to create an Issue on GitHub, and we’ll look into it.

On that note, we want to thank our community so far for helping us create an extensive plugin universe. Without your contributions, we would not have much to showcase.

## More Medusa

If you want to know more about our recent release and product priorities head to our [April’23 Recap](https://medusajs.com/recap/). Otherwise, stay in touch via our newsletter for more product updates.


Introducing Medusa’s Plugins Library

Extending Medusa Example: Creating a Marketplace

Find related blog posts below

Want to know more about Medusa

We're excited to announce a new plugin that provides developers with a better way to manage and deploy Admin for Medusa stores.

This plugin introduces a new approach for shipping the dashboard and lays the groundwork for other product improvements planned for Admin later this year. Specifically, we plan to support admin extensibility, essential for enabling developers to build rich commerce applications. With the ability to extend the admin UI with plugins and extensions, developers will be able to create solutions that meet their end-to-end use cases.

Although admin extensibility is still in development, this initial step provides developers with more options and improves the developer experience of deploying and maintaining Admin.

## Seamless Updates

With the move to distributing Medusa’s Admin through `npm` we will also ensure that Medusa Admin is versioned. Prior to this release, the dashboard was available through a GitHub repository, and users must keep up with the latest changes. This has sometimes led to version mismatches and incompatibilities between the UI and server.

With the new introduction of admin as an NPM package, users can update their admin with a single command. The plugin's versioning follows major and minor updates to the Medusa core, ensuring users can update their admin without worrying about compatibility issues.

## Flexible Deployment Options

Developers have two options for deploying Admin using the plugin. They can either integrate it as a part of their server, where the dashboard is directly served from an endpoint, or they can use the plugin as a build tool and deploy the dashboard to a hosting service such as [Vercel](https://docs.medusajs.com/deployments/admin/deploying-on-vercel).

Users can also combine both options. They can use integrated hosting while in development to have a simple development environment when building with Medusa. Later, they can opt for deploying to an external host in production to leverage modern infrastructure tools.

## An Integrated Part of Your Store

Medusa’s mission is to equip developers with the necessary tools to create robust commerce applications. Medusa's extensible core makes this possible. With this plugin, we're bringing Admin closer to the core. This opens the door to many new, exciting possibilities, including allowing developers to create admin extensions directly from their server directory or through plugins. This will give plugin maintainers the ability to create end-to-end extensions. We're currently in the process of creating a new Extensions API, and we'll share more on this soon.

## Trying it Out

As mentioned, the plugin provides developers with two options for deployment. In this section, we will cover how to host Admin as an integrated part of your server. For information on deploying Admin to an external host, please refer to our [documentation].

## Installing the Plugin

To install the plugin, use your preferred package manager:

```bash
yarn add @medusajs/admin
```

Then configure it in `medusa-config.js`:

```js
const plugins = [
  // ...
  "@medusajs/admin"
];
```

In `package.json` we need to add a new script to build the dashboard:

```json
"scripts": {
	// ...
	"build:admin": "medusa-admin build"
}
```

We can now build Admin and start up our server

```bash
yarn build:admin
yarn start
```

The dashboard can now be accessed from your browser. If you run Medusa on the default port, the URL is ``.

![](/images/FtMuPMrHJ1.png)

## What's next?

We have several exciting improvements planned for the Admin in the coming months. Currently, we are improving our design system and will ship a new component library to go along with it. Our goals are to enhance the overall look and feel of the dashboard and its responsiveness, and to introduce a new dark mode theme. The new component library will be open-sourced, and we hope developers will find it useful when creating admin extensions once the Extensions API is released later this year.

For a full overview of what we have planned for Admin and Medusa, you can read more on our [GitHub discussions page](https://github.com/medusajs/medusa/discussions/categories/roadmap). We would love to hear any feedback and ideas you might have for the next features we are working on, so please do not hesitate to share them with us.

You can learn more about the [admin plugin in our documentation](https://docs.medusajs.com/admin/quickstart).


Announcing Admin plugin

[Medusa](https://medusajs.com/) provides commerce building blocks for developers to build rich commerce applications. With the latest evolution of our toolkit towards a more modular architecture, we are taking steps to make Medusa more agnostic to infrastructure. As a big step in this direction, we are excited to announce Medusa’s new cache modules.

In this article, we will look under the hood to see how cache modules work, which cache module you can use in your project today, and, finally, we will demonstrate how easily a Memcached module can be built.

## How it works

Cache modules in Medusa implement the [`ICacheService`](https://github.com/medusajs/medusa/blob/develop/packages/types/src/cache/service.ts) interface and are used internally to cache data like product prices and tax rates.

Medusa’s default starter project comes with an in-memory cache module (`@medusajs/cache-inmemory`) pre-installed, which uses a plain JavaScript Map object to store data. This is great for testing and development purposes, but not recommended for production environments. You can have one cache module installed at a time and for production environments, we have built a cache module that uses Redis (`@medusajs/cache-redis`). To enable the Redis cache module, simply install the package:

```bash
yarn add @medusajs/cache-redis
```

And configure it in your `medusa-config.js` file:

```js
module.exports = {
  //...
  modules: {
  	// ...
		"cacheService": {
			resolve: "@medusajs/cache-redis",
			options: { ttl: 30, redisUrl: REDIS_URL }
		}
	},
};
```

And that’s it. With just a couple of changed config lines, you use a different data store for our caching layer.

## Building a cache module

As mentioned above, we are making in-memory and Redis cache modules available today. Building a new cache module is, however, very easy if you have a different caching tool in place already or prefer another caching technology. To demonstrate how to build a cache module, we will implement `ICacheService` to work with Memcached. For communication with the Memcached instance, we will be using the [Memcached client for Node.js](https://www.npmjs.com/package/memcached).

The first thing to do is to create our project. We need a basic TypeScript project configured for Node. You can clone a preconfigured starter [here](https://github.com/fPolic/medusa-cache-memcached/tree/setup), and after running `yarn install`, start building.

To implement the service, create a new TypeScript file in `src/services`:

```ts
// src/services/memcached-cache.ts

import Memcached from "memcached" // 1. Memcached client
import { ICacheService } from "@medusajs/medusa" // 2. Interface from medusa core that all caching modules need to implement

const DEFAULT_CACHE_TIME = 30 // 3. Keep data cached for 30 seconds

/**
 * 4. Module config type.
 * Defines which options can be passed to the module in the medusa-config file.
 */
type MemcachedCacheModuleOptions = {
  /**
   * Time to keep data in the cache (in seconds)
   */
  ttl?: number

	/**
		* Allow passing the configuration for Memcached client
		*/
  location: Memcached.Location
  options?: Memcached.options
}

type InjectedDependencies = {}

class MemcachedCacheService implements ICacheService {
  protected readonly memcached: Memcached
  protected readonly TTL: number

  constructor(
		{}: InjectedDependencies,
    options: MemcachedCacheModuleOptions // 5. Options passed as module config will be injected here by the modules loader
  ) {
    this.memcached = new Memcached(options.location, options.options) // 6. Instantiate Memcached client for communication with the Memcached instance
    this.TTL = options.ttl || DEFAULT_CACHE_TIME
  }

 /**
   * Set a key/value pair to the cache.
   * It is also possible to manage the `ttl` through environment variables using CACHE_TTL. If the ttl is 0 it will
   * act like the value should not be cached at all.
   */
  async set(
    key: string,
    data: Record<string, unknown>,
    ttl: number = this.TTL
  ): Promise<void> {
    return new Promise((res, rej) =>
      this.memcached.set(key, JSON.stringify(data), ttl, (err) => {
        if (err) {
          rej(err)
        } else {
          res()
        }
      })
    )
  }

  /**
   * Retrieve a cached value belonging to the given key.
   */
	async get<T>(cacheKey: string): Promise<T | null> {
    return new Promise((res, rej) => {
      this.memcached.get(cacheKey, (err, data) => {
        if (err) {
          res(null)
        } else {
          if (data) {
            res(JSON.parse(data))
          } else {
            res(null)
          }
        }
      })
    })
  }

  /**
   * Invalidate cache for a specific key.
   */
  async invalidate(key: string): Promise<void> {
    return new Promise((res, rej) => {
      this.memcached.del(key, (err) => {
        if (err) {
          rej(err)
        } else {
          res()
        }
      })
    })
  }
}

export default MemcachedCacheService
```

And that’s it. The final thing to add is export from the `index.ts` file like so:

```ts
// src/index.ts

import { ModuleExports } from "@medusajs/modules-sdk"

import { MemcachedCacheService } from "./services"

const service = MemcachedCacheService

const moduleDefinition: ModuleExports = {
  service,
}

export default moduleDefinition
```

You can find the entire implementation [here](https://github.com/fPolic/medusa-cache-memcached/blob/main/src/services/memcached-cache.ts).

To test the module with a Medusa instance, [link](https://classic.yarnpkg.com/lang/en/docs/cli/link/) your module project with a Medusa instance:

```bash
// first build the package from the root
yarn build

// register package
yarn link
```

Next, we need to add this package to our Medusa project and tweak our `medusa-config.js` file:

```bash
// in the root of your Medusa project run:
yarn link medusa-cache-memcached
```

```js
// medusa-config.js
module.exports = {
  // ...
  modules:{ 
		// ...
		"cacheService": 
			{
				resolve: "medusa-cache-memcached", 
				options: { location: "localhost:55000" }}
			},
};
```

With this example, we see how straightforward it is to build a (cache) module for Medusa. This, combined with the fact that Medusa is an open-source project, shows the advantages users of such projects have in terms of a growing ecosystem of existing modules.

## What’s next

The introduction of cache modules is a step in adding infrastructure agnosticism to Medusa’s architecture. This will make it easier to integrate Medusa into existing stacks and improve the developer experience. Our introduction of [EventBus modules](https://medusajs.com/blog/announcing-event-bus-modules) is a similar evolution to Medusa’s architecture. We are excited to see what you build with these new tools and can’t wait to launch more modules in the near future.

Learn more about [Cache Modules in our documentation](https://docs.medusajs.com/development/cache/overview).


Announcing Cache Modules

Today, we are announcing a significant update and change to the events system of Medusa. We are moving part of the Event Bus from the core package to a separate module. Our continuous efforts to build a more modular and flexible engine motivate the decision.

In a space with continuous innovations and fierce competition, the ability to adapt your product to changes, run experiments, and leverage new technology becomes highly relevant for businesses to stay ahead (or keep up) with the competition.

To do so, you need flexibility in your setup.

At Medusa, we strive to provide merchants and developers with the building blocks to create bespoke experiences. These building blocks give you a strong starting point and are created to be replaced with more advanced functionality as your business grows, and your needs change.

The flexibility and ease of customization enable businesses to focus on building the best product for their customers without worrying about the typical triennial migration project.

The Event Bus modules give businesses the freedom to choose the technology to power the events system of Medusa.

## What are modules?

Until now, Medusa has offered two ways of extending or replacing core functionality with custom implementations or third-party services; through [Strategies](https://docs.medusajs.com/advanced/backend/batch-jobs/customize-import/) and [Plugins](https://docs.medusajs.com/advanced/backend/plugins/overview/).

Strategies allow you to override an isolated piece of business logic e.g. cart completion or product import, and plugins are used to build custom features or integrate services with your engine. The latter is especially well-suited for when you want several of the same type of services installed, e.g. payment providers.

Modules allow you to replace business domains or specific elements in your stack with pre-built functionality, custom implementations, or third-party providers. They can be shipped through `npm` and are configurable in `medusa-config.js` - similar to plugins.

The main difference between Modules and Strategies and Plugins, in the context of business domains, is that Modules do not necessarily share application scope and resources with the core. Effectively, this means that a module can live without dependencies on core concepts and be powered by a separate data store.

This unlocks a multitude of opportunities, as you can power entire domains of Medusa with third-party APIs or custom implementations that fit your organization’s needs. Let’s take user authentication as an example. Separating the Users domain into a module will allow businesses to use providers like Okta to manage everything related to users, authentication, roles, etc. -  without shoehorning an existing feature to work correctly through an integration.

Refer to [our documentation for a detailed walkthrough of the Modules API](https://docs.medusajs.com/development/modules/overview), including setup and building one yourself. In this post, we only briefly explain simple usage and configuration.

## Event Bus module

One of the first use cases of modules is within the events' domain. We are introducing an Event Bus module enabling businesses to use any available pub/sub technology to power the message broker of Medusa.

We still offer a fully functional event bus powered by Redis out-of-the-box, but instead of being baked into the core, you must install and configure it.

Additionally, we are replacing the default event bus, which previously used a mocked Redis instance, with a [local event bus module](https://docs.medusajs.com/development/events/modules/local) powered by the Node EventEmitter. This module is not recommended for a production environment.

You’ll find more details about the Redis event bus functionality and configuration in [the documentation](https://docs.medusajs.com/development/events/modules/redis).

### Installation

The following steps should be taken to install the Redis Event Bus and upgrade your existing setup to use the Modules API.

These are the required steps for any module going forward - unless the module comes with a default package; in that case, you only need to install the `npm` package in your Medusa project.

**Installing the Redis Event Bus**

Install the Redis event bus with `npm`:

```bash
yarn add @medusajs/event-bus-redis
```

Configure it in `medusa-config.js`:

```js
module.exports = {
  projectConfig: {
    database_url: DATABASE_URL,
		...
  },
  modules: {
    eventBus: {
      resolve: "@medusajs/event-bus-redis",
			options: {
        redisUrl: "redis://...",
      },
    },
  },
  plugins: ["medusa-payment-stripe"],
};
```

Again, we won’t cover the details of the configuration in depth - our documentation serves that purpose - but only briefly explain the code snippet above.

We use the new `modules` property on the project configuration object to specify the modules we want to override or add. The keys of this object are defined and exposed in the core, ensuring that modules are correctly registered.

The module key for the event bus is, you guessed it, `eventBus`. The value of the key is the module configuration. The `resolve` property points to the package you want to use and can be an `npm` package or a path to a local implementation.

The `options` property is a set of required and optional settings that are injected into the module. The only required property for the Redis Event Bus is the URL of your Redis instance. Other optional settings can be found in the documentation.

After performing these steps, you can restart your Medusa instance, and everything will work as always, but your events system will be configured and powered by our Modules API.

## Summary

The Modules API is a huge step toward a more composable architecture and will play a critical role in all our work as we advance. The Event Bus module is one of the first demonstrations of the API’s capabilities, though it does not do it full justice. The full power of the API will be more evident as we move into the business domains e.g. multi-warehousing. Read the [product announcement here](https://medusajs.com/blog/announcing-multi-warehouse).

The Event Bus module abstraction is valuable for products and companies that use Medusa as part of their larger system, as they typically have existing messaging infrastructure in place. Giving them the ability to use this infrastructure to power events in Medusa will make the integration easier and reduce costs and stack complexity.

The abstraction is also valuable for developers unfamiliar with Redis or BullMQ (our message queue library). It allows them to replace the technology of the events system with a framework they are more comfortable with, thus offering a better developer experience.

You can learn more about [the events system in our documentation](https://docs.medusajs.com/development/events/)

Give the new modules a try, and let us know what you think. Feedback is highly appreciated.


Announcing Event Bus Modules

On March 15th, we rolled out a new [Medusa documentation](https://docs.medusajs.com/) with a cleaner design and a straightforward structure. This is part of our mission to constantly improve our developer experience and help guide developers in their journey using Medusa.

In this article, I’ll detail the thought process, planning, and general work that went into revamping our documentation.

![](/images/qysrRNH_A6.gif)

## Problems with the Previous Documentation

A few months back, I wrote an article about [how we improved our documentation](https://medusajs.com/blog/how-we-improved-our-documentation/) at Medusa. In that article, I discussed why and how we decided to take a product approach towards documentation.

![](/images/edwfMn9F4E.png)

This lead to an improvement to our documentation from its initial state both in design, structure, and development tools and processes.

![](/images/-i90gZaZ2A.png)

However, it wasn’t long until we realized that although this was a huge improvement, it was still lacking in different areas.

### Documentation Structure

Our approach to structure was simple: if a documentation page was a tutorial or a guide that informed developers how to perform something, we put it under the “How-to Guides” category; if a documentation page was a conceptual guide explaining how a feature or a tool generally works, we put it under the “Conceptual Guides” category.

Although we believe in the beauty of simplicity, this approach was too simple for a solution like Medusa. Medusa is not an ecommerce platform that can be used in a single use case. Medusa provides the building blocks to build commerce applications. It can be used to create a fully-fledged ecommerce system, or some of its modules can be used within a larger microservice or composable architecture.

So, categorizing documentation pages that may cover topics related to the Medusa backend, the storefront, the admin, or other areas under general categories such as “How-to Guides” or “Conceptual Guides” became limiting. It made it difficult for developers to find the guide they’re looking for in a specific area, and it was misguiding, as it didn’t properly inform developers of the different ways they can use Medusa.

### Documentation Design

The previous design was a major step-up from the initial design we had, but it mainly lacked in visual elements that can help developers differentiate between different sections or areas of the documentation.

In addition, while performing user trials — where we ask developers to use our documentation to perform a task in Medusa — we received comments about some confusion while using the sidebar due to how it was designed.

## Planning for the New Documentation

As documentation is essential for a pleasant developer experience, our documentation team decided it was time to look into how we can improve our documentation.

### Figuring out the Information Architecture

We started off by building a new information architecture for the documentation. We created a hierarchy of the areas in Medusa, starting from the too-general categories and getting down to specifics.

For example, in the previous architecture, we stuffed the How-to category with guides that were not remotely related to one another. So, you would find a guide on how to implement a cart in the storefront right next to a guide on how to create an endpoint.

We started de-structuring that architecture to find the top-level main areas of interest, and work our way down from there. These areas ended up being [Commerce Modules](https://docs.medusajs.com/modules/overview) — which covered all guides related to commerce features, such as the implement cart guide — and [Medusa Development](https://docs.medusajs.com/development/overview) — which covered the fundamentals of developing with Medusa, such as the create endpoint guide.

Then, we would dive into the structure of each of these top-level areas and work our way down from there. For example, inside Commerce Modules, the guides should be categorized by each module. Within the category of each module, we categorized the guides based on whether they’re architectural guides or how-to guides, and what areas do these guides tackle (for example, admin or storefront).

Taking this granular approach towards categorizing the documentation can easily become too confusing. So, it was important to also design a journey that allows developers to find their next steps and not get lost within this architecture. This was a combination of writing an informative content structure and providing visual elements and effects to make the journey even clearer to developers.

### Re-designing the Documentation

After coming up with the initial draft of our new information architecture, we started working on the design to bring it to life. The redesigning of the documentation involved redesigning existing elements and creating new elements that provided visual values.

For example, we moved towards using descriptive icons in our main sidebar. We also redesigned the global sidebar within the documentation to ensure the categorizing and hierarchy is visually visible and clear.

Part of the redesign was also maintaining a consistent design system within our products at Medusa. So, the documentation now uses the same design system that products like the Admin use.

### Building the New Documentation

The last piece of the puzzle was building the new documentation. This included modifying existing functionalities and components, building new components, and reflecting the Medusa design system into the documentation.

One component we changed was the Feedback component that can be seen at the end of documentation pages. Although this component provided us with insightful feedback from developers using our documentation, we realized that we weren’t actually providing developers with any solutions if they run into any problems.

So, we revamped the Feedback component that provides possible solutions from closed GitHub issues. The issues are shown either based on the message that the developer enters, or based on the page they’re in.

![](/images/feedback-component.gif)

## The Final Result

The new documentation was a product of a lot of discussions and brainstorming to come up with an improved developer experience. After numerous rounds of iterations and improvements, we decided to roll out the new documentation.

As always, this in no way means that the documentation is now perfect or finished, and it should be no surprise if later in the year you find another article on how we — again — improved our documentation. Documentation is a continuous learning and growing experience as we further understand developers using Medusa, and as we further innovate with Medusa.

We look forward to any feedback you have, which you can always send on our [Discord](https://discord.gg/medusajs), GitHub [issues](https://github.com/medusajs/medusa/issues) and [discussion](https://github.com/medusajs/medusa/discussions), or using the feedback form within our documentation.


Announcing Medusa’s New Documentation

Developers

Company

Main Menu

Learn More

This plugin does not have a README.

If you want to learn how to use this plugin, we recommend one of the following steps:

1. Join our [Discord community](https://discord.gg/medusajs) and ask for help on how to use this plugin.
2. Reach out to the plugin's author to learn how to use it.