A ready-to-use multi-vendor marketplace built with MedusaJS and Next.js. Deploy to Railway in minutes.
This is a complete marketplace solution with:
- Multi-vendor marketplace with commission management
- Stripe Connect for vendor payments
- Next.js 15 storefront (App Router, i18n, Tailwind)
- Customized admin panel for vendors
- Real-time chat between customers and vendors
- Product search with Algolia
- Email notifications via Resend
- Monorepo setup with PNPM and Turbo
- CI/CD pipeline with GitHub Actions
git clone https://github.com/dtoyoda10/mercur-railway-boilerplate.git cd mercur-railway-boilerplate pnpm install cp apps/backend/.env.template apps/backend/.env cp apps/storefront/.env.template apps/storefront/.env cp apps/vendor-panel/.env.template apps/vendor-panel/.env # Edit the .env files with your config pnpm run db:init pnpm run db:admin pnpm run dev
Access at http://localhost:8000 (storefront) and http://localhost:7000 (admin)
For detailed instructions, see QUICKSTART.md
Getting Started
- Quickstart - Get running in 5 minutes
- Complete Setup Guide - Local development and Railway deployment
- Environment Variables - All configuration options
Integrations
- Stripe Setup - Payments and vendor payouts
- Resend Setup - Email notifications
- Algolia Setup - Product search
- TalkJS Setup - Customer chat
Operations
- Database Management - Migrations and backups
- Security - Best practices
- Monitoring - Health checks and alerts
- Troubleshooting - Common issues
Before Going Live
- Production Checklist - Pre-launch verification
Before you start:
- Node.js v20 or higher
- PNPM v10 or higher
- Docker (for local development)
- Git
For deployment you'll need accounts on:
- Railway (hosting)
- Stripe (payments)
- Resend (emails)
- Algolia (search)
- TalkJS (chat)
All have free tiers you can start with.
Backend: MedusaJS v2.7, PostgreSQL 16, Redis 7, TypeScript
Storefront: Next.js 15, Tailwind CSS, next-intl
Vendor Panel: Medusa Admin SDK, Vite, Tailwind CSS
DevOps: PNPM, Turbo, GitHub Actions, Railway, Docker
mercur-railway-boilerplate/
├── apps/
│ ├── backend/ MedusaJS API server
│ ├── storefront/ Next.js customer-facing app
│ └── vendor-panel/ Admin dashboard for vendors
├── packages/
│ └── http-client/ Generated API client
├── docs/ Documentation
├── .github/workflows/ CI/CD pipelines
└── docker-compose.yml Local development services
# Start all services pnpm run dev # Start individual services pnpm run dev:api # Backend only pnpm run dev:vendor # Vendor panel only pnpm run dev:store # Storefront only # Database operations pnpm run db:init # Initialize database pnpm run db:migrate # Run migrations pnpm run db:admin # Create admin user # Build for production pnpm run build # Run tests pnpm --filter=backend run test # Code quality pnpm run lint pnpm run format
We have a complete step-by-step guide in docs/deployment/railway.md.
Quick version:
- Fork this repository
- Create a Railway project and connect your fork
- Add PostgreSQL database
- Create 3 services (backend, vendor panel, storefront)
- Configure environment variables
- Deploy
Check the production checklist before launching.
The boilerplate needs several environment variables. Here's what's required:
Backend (apps/backend/.env)
DATABASE_URL=postgres://... JWT_SECRET=your-secret-here COOKIE_SECRET=your-secret-here STRIPE_SECRET_API_KEY=sk_... RESEND_API_KEY=re_... ALGOLIA_APP_ID=... ALGOLIA_API_KEY=...
Storefront (apps/storefront/.env)
MEDUSA_BACKEND_URL=http://localhost:9000 NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_... NEXT_PUBLIC_STRIPE_KEY=pk_...
Vendor Panel (apps/vendor-panel/.env)
VITE_MEDUSA_BACKEND_URL=http://localhost:9000
See docs/environment-variables.md for complete documentation.
Backend won't start
- Make sure PostgreSQL is running:
docker ps - Check your DATABASE_URL in .env
- Verify migrations ran:
pnpm run db:migrate
Can't log in to admin
- Create an admin user:
pnpm run db:admin - Check backend is running:
curl http://localhost:9000/health
Products not showing on storefront
- Verify products are published in the admin panel
- Check NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY is set correctly
More solutions in docs/troubleshooting.md.
Contributions are welcome. Please read CONTRIBUTING.md for guidelines.
Quick steps:
- Fork the repo
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
MIT License - see LICENSE file.
- Documentation: docs/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Built with MedusaJS, Next.js, Railway, Stripe, and other open-source projects.