Building a modern e-commerce platform with Next.js, Medusa, and Payload CMS

This is one of the most exciting challenges I faced, as I learnt two new tools and integrated three different applications and keep them all in sync. This project demostrates how I was able to architect a modular, mantainable and integrated full-stack e-commerce application.

Application Demo

Project Architecture

The project is divided into five distinct services to mantain separatin of concerns:

• /frontend → Next.js (Tailwind CSS, Motion, Medusa UI)
• /backend → Medusa (Commerce API)
• /payload → Payload CMS (Content API)
• /database → Postgress (Storage)
• /redis → Redis Cache (Key-Value Storage)

Each service runs independently but communicates through API calls via Docker containers.

A visual overview of how Next.js, Medusa, and Payload integrate.

Project Creation Process

Medusa and Next.js Starter Template

To kick off the project, I started with the official Next.js and Medusa starter template, an open source boilerplate project mantained by both teams and bringing a frontend already connected to the e-commerce modules.

However, I wanted a more robust local development environment where services could run independently and remain isolated. For that reason, I integrated my own Docker compose configurations into the setup, creating separate containers for the applications.

Medusa + Next.js starter template.

And finally, to give it a unique styling. I integrated Motion into the Next.js frontend. This allowed me to add add animations, and interactive effects that enhance the overall user experience. Beyond motion design, I also developed some custom components to refine the UI, bringing a better align with a modern e-commerce aesthetic balancing.

Updated UI with custom components and motion animations.

Extending Medusa with Payload CMS

While Medusa provides powerful e-commerce APIs for products, collections and categories, there was a need to implement content management capabilities to empower the data visualization and organization in the frontend.

For this, and following Medusa's official integration guide, I created a new Payload CMS project, implementing also synchronization with Medusa via subscribers and workflows. This setup ensures that when a product, collection, or other entity is created or updated in Medusa, the changes automatically propagate to Payload — keeping both systems in sync.

As a result, Payload can now extend Medusa’s default properties, enabling richer content editing and more flexible frontend rendering.

Medusa extended collection in Payload CMS

Conclusions

This project showcases the challenge of building a modular headless e-commerce architecture, by using Next.js, Medusa and Payload CMS.

This could be a starting point for any professional e-commerce site, as Medusa provides an extensive capability of e-commerce features, including inventory, order reports and many more. And with the Headless CMS integration this whole application content is fully dynamic and scalable.

If you’d like to explore the codebase or contribute, feel free to check out the repository:

👉🏻 GitHub – E-commerce with Next.js, Medusa, and Payload