Medusa v2 Starter Guide: What's Included and How to Extend It

Medusa v2 is the most serious open-source challenger to Shopify for headless ecommerce in 2026. It ships a complete backend (products, inventory, orders, customers, Stripe payments, admin dashboard) as an open-source Node.js project you can run yourself — no platform fees, no revenue share, no vendor lock-in.

But "open source" is a double-edged sword. You get total control and unlimited customization — and you're responsible for the operational work Shopify normally handles for you. This guide walks through what Medusa actually gives you, how the starters on MVPHub are structured, and the decision points that matter most when you're evaluating it against hosted alternatives.

---

TL;DR

• Medusa v2 is a complete commerce backend with admin dashboard, Stripe integration, and a TypeScript SDK — all open source and self-hostable.
• You get it for free; hosting costs ~$50-200/month for a production stack.
• You save 2-3% of GMV that would go to Shopify platform fees.
• You trade that for running a Node.js backend: uptime, backups, patches, upgrades.
• Pick it when GMV is high enough that fee savings outweigh ops cost, or when you need backend customization Shopify won't allow.
• Skip it when you need to launch fast, have no Node.js ops capacity, or are under ~$500k GMV.

Browse Medusa starter templates on MVPHub

---

What's in the box

Every Medusa v2 starter template on MVPHub ships as a Turbo monorepo with three main pieces:

1. The Medusa backend (apps/backend)

A standalone Node.js service built on top of Medusa v2 (currently 2.13.x). Running the stack locally gives you:

• Product management — products, variants, categories, collections, inventory
• Customer management — accounts, addresses, order history
• Order management — cart, checkout, fulfillment states, returns, refunds
• Payment processing — Stripe plugin wired up out of the box
• Admin dashboard — separate React app for merchants, accessible at /admin
• REST and JS SDK access — consume from any frontend

Under the hood, Medusa runs on:

• Node.js 20 LTS
• PostgreSQL for the main database
• Redis for event bus and caching
• TypeScript for the whole codebase

2. The Next.js storefront (apps/storefront)

A production-grade Next.js 16 storefront that consumes the Medusa backend via the @medusajs/js-sdk package. Features include:

• Product browsing with server-rendered pages (SSR + ISR)
• Cart management via cookie-stored cart ID
• Stripe Elements checkout integration
• Customer accounts and order history
• Wishlist and saved items
• Responsive design with Tailwind CSS and shadcn/ui

3. Shared packages (packages/*)

A shared config and types package keeps the backend and storefront aligned. Common patterns:

• Product types generated from Medusa's schema
• Shared Zod schemas for form validation
• Currency and pricing helpers
• API client with typed endpoints

This monorepo structure is important: you can add a React Native mobile app (apps/mobile) that consumes the same shared packages and Medusa API, and everything stays in sync.

---

How Medusa v2 differs from v1

If you've used Medusa v1, v2 is a major rewrite. Key differences:

• Module system. v2 splits functionality into modules (Product, Inventory, Pricing, Order, etc.) that can be composed or replaced independently. v1 had a monolithic service architecture.
• Workflow system. v2 introduces workflow definitions for multi-step processes (place order, fulfill order, return order). Workflows are composable, testable, and declarative.
• Link system. v2 replaces ORM-level relations with a "links" abstraction that lets modules connect without hard coupling. This makes module swapping realistic.
• TypeScript throughout. v2 is TypeScript-first; types flow through the entire stack.
• Admin dashboard. The admin UI is now a standalone app rather than embedded, which makes custom branding and deployment easier.

The short version: v2 is the version you should start with. v1 is in maintenance mode and new stores shouldn't pick it up.

---

Setting up a Medusa starter locally

Every MVPHub Medusa starter ships with the same setup flow:

# 1. Clone and install
git clone <template-repo>
cd <template-repo>
pnpm install

# 2. Start PostgreSQL and Redis (via Docker)
docker compose up -d

# 3. Copy environment files
cp apps/backend/.env.example apps/backend/.env
cp apps/storefront/.env.example apps/storefront/.env

# 4. Run Medusa migrations and seed data
cd apps/backend
pnpm medusa db:migrate
pnpm medusa seed

# 5. Start everything
cd ../..
pnpm dev

You end up with:

• Backend API at http://localhost:9000
• Admin dashboard at http://localhost:9000/admin (create an admin user first)
• Storefront at http://localhost:8000

Initial setup is 15-30 minutes if you have Docker and pnpm installed.

---

The hard parts: what to expect after launch

Most teams underestimate the ongoing work. Here's what running a Medusa backend in production actually looks like.

Hosting

A production Medusa stack typically has:

• Node.js server for the Medusa API — $10-50/month on Render, Railway, Fly.io, or DigitalOcean App Platform
• PostgreSQL — $15-100/month depending on size
• Redis — $10-30/month
• Storage bucket for images — $5-20/month on S3 or R2
• CDN for image delivery — usage-based, typically $10-50/month
• Email delivery (order confirmations, password resets) — $10-30/month on Resend/Postmark

Total: ~$60-300/month for a realistic production store. That's meaningfully more than Shopify's base plan ($29-79/month), but Shopify also charges 2-3% of GMV on top — so the crossover point is typically around $1M GMV/year.

Maintenance

Expect to spend 4-8 hours per month on:

• Security patches — Node.js, PostgreSQL, Next.js, and Medusa itself all ship patches regularly
• Medusa version upgrades — minor releases land every 1-2 months; major releases every 6-12 months
• Dependency drift — npm packages in your node_modules need periodic refresh
• Database migrations — new Medusa features sometimes require schema migrations
• Backup verification — test that restore actually works (it's not backed up until you've restored it once)

None of this is hard; it's just work. If nobody on your team will do it, Medusa is the wrong choice.

The Shopify comparison

---

How to extend Medusa

Medusa v2's module system makes extension realistic in ways that monolithic ecommerce platforms don't allow. The main extension points:

Custom modules

You can add your own module (e.g., a "Wholesale Pricing" module) that Medusa links into the product and order flows. The module system handles dependency injection, database migrations, and event subscription for you.

Custom workflows

Workflows define multi-step business processes. Need "quote approval before order placement" for B2B? Write a workflow that inserts an approval step. Need custom fulfillment logic? Extend the fulfillment workflow.

Custom API routes

Medusa uses Express-like routing under the hood. You can add routes for anything not covered by the built-in APIs — integrations, webhooks, custom admin endpoints.

Event subscribers

Every important event (order placed, payment captured, customer created) emits on the event bus. You can subscribe to any event to trigger side effects (send emails, update external systems, log analytics).

Frontend is entirely yours

Unlike Shopify themes, the storefront is just a Next.js app you own. Any design, layout, or interaction is fair game — no theme editor constraints.

---

When to actually pick Medusa

Be honest about whether your situation matches these criteria:

Pick Medusa if:

• You're doing or planning $1M+ GMV/year (fee savings justify ops cost)
• You need custom checkout, pricing, or fulfillment logic Shopify won't allow
• You have Node.js engineering capacity (or can hire it)
• You're building a B2B store with quote-based pricing or customer-specific catalogs
• You want to avoid Shopify platform lock-in long-term
• You're building something non-standard (subscription commerce, marketplace, custom fulfillment)

Don't pick Medusa if:

• You're under $500k GMV and will stay there (Shopify is cheaper)
• You need to launch in less than 4 weeks
• You have no one to run the backend
• Your design requirements are satisfiable by a Shopify theme
• You're replatforming from Shopify and your team doesn't have strong feelings about why

Most teams who say "Medusa" when they mean "cheaper Shopify" end up back on Shopify in a year. Pick it because you need the control, not because you want to avoid fees.

---

MVPHub templates with Medusa backends included

Three MVPHub templates currently ship full Medusa v2 backend variants:

• Christmas Gift Store — holiday-themed storefront with full Medusa backend, ideal for seasonal pop-ups
• Perfume Store — luxury-styled fragrance storefront with Medusa backend, tuned for premium brand presentation
• T-Shirt Store — apparel storefront with a production-ready Next.js frontend and Medusa backend

All three include the Medusa monorepo structure, seeded sample data, Stripe integration, and deployment documentation. Browse Medusa starters to see the full list and demos.

---

Next steps

• Browse all Medusa starter templates
• Compare Next.js ecommerce templates — Medusa vs Shopify vs custom
• Read the Shopify headless guide if you're still deciding
• Read the headless architecture pillar guide
• Check compatibility matrix — Medusa support across deployment targets
• See performance benchmarks — real Lighthouse scores for Medusa-backed storefronts

Medusa v2 is a serious platform. Pick it for the right reasons — backend control, fee savings at scale, custom business logic — and it will carry you a long way. Pick it for the wrong reasons and you'll be back on Shopify in a year, wishing you'd done less engineering work.