The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
Mercur Basic Template
This template comes configured with the bare minimum to get started building your marketplace with Mercur.
Quick Start
To spin up this template locally, follow these steps:
Clone
If you've already cloned this repo, skip to Development.
Development
First clone the repo if you have not done so already
Copy the example environment variables:
cd my-project
cp packages/api/.env.template packages/api/.env
- Update the
.envfile with your database connection string and other required variables:
DATABASE_URL=postgres://user:password@localhost:5432/mercur
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-super-secret-jwt-key
COOKIE_SECRET=your-super-secret-cookie-key
- Install dependencies and start the dev server:
bun install
bun dev
- Open
http://localhost:9000to access the Medusa backend - Open
http://localhost:7000to access the admin dashboard - Open
http://localhost:7001to access the vendor dashboard
That's it! Follow the on-screen instructions to login and create your first admin user.
What's Inside
This monorepo includes the following packages and apps:
Apps and Packages
packages/api- The Medusa backend with all marketplace functionalityapps/admin- Admin dashboard customizationsapps/vendor- Vendor portal customizations
Project Structure
├── apps/
│ ├── admin/ # Admin dashboard extensions
│ └── vendor/ # Vendor portal extensions
├── packages/
│ └── api/ # Medusa backend
│ ├── src/
│ │ ├── api/ # Custom API routes
│ │ ├── jobs/ # Background jobs
│ │ ├── links/ # Module links
│ │ ├── modules/ # Custom modules
│ │ ├── scripts/ # CLI scripts
│ │ ├── subscribers/ # Event subscribers
│ │ └── workflows/ # Business workflows
│ └── medusa-config.ts
├── blocks.json # Mercur blocks configuration
├── package.json
└── turbo.json
Utilities
This project has some additional tools already setup for you:
- TypeScript for static type checking
- Turborepo for monorepo management
- Prettier for code formatting
How It Works
The Mercur basic template is built on top of Medusa and is pre-configured for marketplace functionality.
Modules
Custom modules allow you to extend the core functionality. See the Modules docs for details.
Workflows
Workflows define multi-step business processes. See the Workflows docs for details.
API Routes
Custom API routes expose HTTP endpoints. See the API Routes docs for details.
Links
Links define relationships between modules. See the Links docs for details.
Adding Blocks
You can extend your project with pre-built blocks using the Mercur CLI:
bunx @mercurjs/cli add block-name
Configure your block sources in blocks.json:
{
"aliases": {
"workflows": "packages/api/src/workflows",
"links": "packages/api/src/links",
"api": "packages/api/src/api",
"modules": "packages/api/src/modules"
},
"registries": {}
}
Build
To build all apps and packages:
bun run build
AI agents
This project bundles its documentation as a dependency (@mercurjs/docs), so AI agents can read it offline and version-matched to your installed packages. Point your agent at:
node_modules/@mercurjs/docs/llms.txt— an index of every pagenode_modules/@mercurjs/docs/content/**/*.mdx— the full pages
CLAUDE.md and AGENTS.md instruct agents to read these before making changes. The same docs are online at docs.mercurjs.com.
Questions
If you have any issues or questions start a GitHub discussion.