Mercur

JavaScript Open Source Multi-Vendor Marketplace built on top of Medusa.js.

What is Mercur?

Mercur is the first JavaScript open-source platform for building multi-vendor marketplaces. Built on top of Medusa.js, it simplifies the development of customized marketplaces.

Why Mercur?

After seeing the rising trend in multi-vendor business models and setting up several marketplaces from scratch at Rigby, we wanted to eliminate the repetitive setup of marketplaces.

The aim is to enable users to start a new marketplace in about five minutes, providing a strong starting point for anyone looking to build their own multi-vendor platform.

Medusa is an amazing and strong foundation for building marketplaces but requires a few modifications to adjust to this business model. We wanted a faster way to get these platforms up and running — Mercur is that accelerator for building multi-vendor marketplace with Medusa.js as a core.

Goals

We aim to make Mercur adaptable for various marketplace types, such as rental or service marketplaces.

We also want to build an ecosystem of plugins tailored to multi-vendor setups, including solutions for payment distributions like Stripe. We want to publish all plugins adapted to the multi-vendor market under the name medusa-mercur-... e.g. medusa-mercur-stripe. With this annotation, developers will always know that this is a plugin for the MVM.

Feel free to share your ideas on Medusa Discord, how you imagine the development of this project.

Project Components:

Mercur Architecture

Core: The backbone of Mercur, handling the primary operations and data flow essential for marketplace functionality.
Admin: Provides a control panel for marketplace administrators to manage vendors, orders, settings, and more.
Vendor: A dedicated interface for vendors to manage their products, orders, and profile details.
Storefront: The frontend where customers browse products, place orders, and interact with the marketplace. It is a customized version of the Medusa.js Next.js Starter.

Project Features:

Vendor Registration: Allows new vendors to sign up and await approval from marketplace administrators.
Vendor Profiles: Enables vendors to create and customize their profiles on the marketplace.
Vendor Authorization by Admin: Admins can review and authorize vendor registrations to maintain marketplace standards.
Order Splitting: Facilitates the distribution of orders among multiple vendors involved in a single transaction.
Vendor Shipping Management: Vendors can manage their shipping logistics independently within the platform.

Roadmap:

Payment provider & Commission Management & Invoices
Adjustments to Medusa 2.0!
More: coming soon

Getting started 🚀

Create a new Mercur project with the command:

npx mercurjs marketplace

You will be asked to enter the project's name and select the project’s modules (admin / vendor / storefront) platform you wish to use. Once selected, the CLI will create project files in the directory matching your project name.

How to configure

API Configuration

Initial Setup

Navigate to the /api directory.
Execute the yarn command to install dependencies.
Build the admin and vendor ui:s; yarn run build:admin && yarn run build:vendor

Environment Configuration

Create a .env file in the root of the project.
Add the DATABASE_URL variable with your PostgreSQL database URL.

Database and Server Initialization

Seed the database:

yarn seed

Start the Medusa development server:

yarn dev

The server will start on http://localhost:9000.

Admin panel

Navigate to the /api folder.
Run the yarn dev command to start API and admin panel in development mode
Log into the admin panel using the credentials created during the seeding process (admin@medusa-test.com with password supersecret).

Vendor panel

Navigate to the /api folder.
Run the yarn dev:vendor command to start vendor panel in development mode
Register vendor by accessing vendor_url/register page
Approve registered vendor on Users page in admin panel
Log in using vendor credentials
Now you can edit your vendor panel using /vendor folder in src directory (See medusa admin quickstart)

Storefront Setup

Navigate to the /store-front folder.
Run the yarn command to install dependencies.
Create an .env file in the root of the project folder with the following entries:

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_BASE_URL=http://localhost:8000
NEXT_PUBLIC_DEFAULT_REGION=eu
REVALIDATE_SECRET=supersecret

Start the storefront application:

yarn dev

This will launch the storefront, typically available at http://localhost:8000.

Adding a Vendor User

To add a vendor user via the API, follow these steps:

Make a POST request to the endpoint api_url/vendor/users with the body:

{
  "email": "vendoremail@email.com",
  "password": "vendorpassword"
}

Replace api_url with your actual API endpoint URL, typically something like http://localhost:9000.

This will create a new vendor user in the system. Before the vendor can log in, the admin must authorize his registration in the administration panel by making his status active.

Support Mercur ❤️

Mercur is a community-driven, open-source initiative. We are committed to keeping it free and accessible by releasing it under the MIT License.

How to contribute:

Ideas: If you have any ideas on how to develop the product further, feel free to share them with us. We're always open to new suggestions!
Code: Help improve our project by contributing code or fixing bugs. We invite you to review our Contributing Guide.
Bug: Encountered a bug? We encourage you to open an issue on our GitHub repository.
Spread the Word: Tell others about our project. Every mention helps!
Create Content: Write a post, make a video, or create a tutorial. We’ll share your work.
Join the Community: Answer questions and provide support on our Discord.

Useful Links

License

Licensed under the MIT License.

mercurjs / mercur

readme