Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mercurjs/mercur

JavaScript Open Source
Multi-Vendor Marketplace Accelerator build on top of Medusa.js. Mercur simplifies the path to your own customized, multi-vendor marketplace.
https://github.com/mercurjs/mercur

ecommerce javascript marketplace medusajs multivendor-ecommerce nextjs nodejs open-source

Last synced: about 21 hours ago
JSON representation

JavaScript Open Source
Multi-Vendor Marketplace Accelerator build on top of Medusa.js. Mercur simplifies the path to your own customized, multi-vendor marketplace.

Awesome Lists containing this project

README 

        
![Mercur](https://rigby-web.fra1.digitaloceanspaces.com/README-mercur-lg.png)





  
Mercur


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


  

  

  

    License

  

  

    PRs Welcome

  

  

    Support

  



  

  


    Mercur |

    Medusa

  








# 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](https://rigby-web.fra1.digitaloceanspaces.com/mercur-mvm-lgg.png)



- **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:



```bash

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**



1. Navigate to the `/api` directory.

2. Execute the `yarn` command to install dependencies.

3. Build the admin and vendor ui:s; `yarn run build:admin && yarn run build:vendor`



**Environment Configuration**



1. Create a `.env` file in the root of the project.

2. Add the `DATABASE_URL` variable with your PostgreSQL database URL.



**Database and Server Initialization**



1. Seed the database:



```bash

yarn seed

```



2. Start the Medusa development server:



```bash

yarn dev

```



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



#### Admin panel



1. Navigate to the `/api` folder.

2. Run the `yarn dev` command to start API and admin panel in development mode

3. Log into the admin panel using the credentials created during the seeding process ([email protected] with password supersecret).



#### Vendor panel



1. Navigate to the `/api` folder.

2. Run the `yarn dev:vendor` command to start vendor panel in development mode

3. Register vendor by accessing `vendor_url/register` page

4. Approve registered vendor on `Users` page in admin panel

5. Log in using vendor credentials

6. Now you can edit your vendor panel using `/vendor` folder in `src` directory [(See medusa admin quickstart)](https://docs.medusajs.com/admin/quickstart)



#### Storefront Setup



1. Navigate to the `/store-front` folder.

2. Run the `yarn` command to install dependencies.

3. Create an `.env` file in the root of the project folder with the following entries:



```bash

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

NEXT_PUBLIC_BASE_URL=http://localhost:8000

NEXT_PUBLIC_DEFAULT_REGION=eu

REVALIDATE_SECRET=supersecret

```



4. Start the storefront application:



```bash

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:



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



```json

{

  "email": "[email protected]",

  "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



- [Medusa Community Discord](https://discord.gg/medusajs)

- [Mercur website](https://mercurjs.com)

- [Medusa website](https://medusajs.com)

- [Medusa docs](https://docs.medusajs.com/)

- [Medusa repo](https://github.com/medusajs/medusa)



## License



Licensed under the [MIT License](https://github.com/mercurjs/mercur/tree/main?tab=MIT-1-ov-file).