# Medusa

TypeScript commerce modules configured in medusa-config.ts, with complete Admin and Store REST APIs.

Node.js commerce platform whose core modules (cart, order, product, pricing, inventory, and more) are MIT and swapped by configuration. Admin and Store REST APIs with a JS SDK cover the whole surface. The Builder publishes medusa-agent-skills (Claude Code plugins with a docs MCP) for building on it; Medusa Cloud and Enterprise Edition are paid.

Alternative to: Shopify, Adobe Commerce

- Capabilities: adaptable, operable
- Vertical: ecommerce
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/medusajs/medusa (MIT (Enterprise Edition materials under ENTERPRISE-LICENSE.md)), 36110 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/medusajs--medusa.html
- JSON: apps/medusajs--medusa.json

## Use it when

- I am building a DTC or B2B backend in TypeScript and want commerce primitives I can compose rather than a monolith
- my agent should run the store through a documented REST API and learn the framework from the Builder's own skills

## Gotchas

- No storefront in the core; the Next.js starter is a separate repo
- GitHub shows NOASSERTION because Enterprise Edition materials carry a separate license inside the repo
- The agent-skills MCP reads documentation only; it does not operate a store

## Editions

- Open source: Free, open source
  - source: npx create-medusa-app@latest
- Medusa Cloud: Free, closed source
  - hosted: https://medusajs.com/cloud/
- Enterprise Edition: Free, closed source

## Adaptable: make it yours

Effort: light-edit (18 things to edit)

create-medusa-app scaffolds a project; medusa-config.ts (projectConfig, admin, modules, plugins, featureFlags) reads .env for DATABASE_URL, CORS origins, secrets, and Redis. Modules are swapped by config; custom behavior is a module, workflow, or API route in src/. The storefront is a separate Next.js starter. The Builder's medusa-dev skills exist for exactly these edits.

- Env vars: DATABASE_URL, DATABASE_NAME, REDIS_URL, JWT_SECRET, COOKIE_SECRET, STORE_CORS, ADMIN_CORS, AUTH_CORS, MEDUSA_BACKEND_URL, PORT, HOST, LOG_LEVEL, WORKER_MODE, MEDUSA_DISABLE_TELEMETRY, ADMIN_AUTH_TYPE
- Config files: medusa-config.ts, .env
- Prompt files: medusa-agent-skills plugins (medusa-dev, ecommerce-storefront, medusa-cloud)
- Accounts you'll need: Medusa Cloud (hosted edition only)

## Operable: what an agent can drive

Operability: official. Interface: api at https://docs.medusajs.com/api/admin (published by the builder, local).

### Reach (complete coverage)

- Manage products, variants, categories: reachable. Admin API /admin/products, /admin/product-categories
- Manage orders, fulfilments, returns: reachable. Admin API /admin/orders, /admin/fulfillments, /admin/returns
- Manage customers and groups: reachable. Admin API /admin/customers
- Pricing, price lists, promotions: reachable. Admin API /admin/price-lists, /admin/promotions
- Inventory and stock locations: reachable. Admin API /admin/inventory-items, /admin/stock-locations
- Regions, sales channels, shipping options: reachable. Admin API /admin/regions, /admin/sales-channels, /admin/shipping-options
- Storefront cart and checkout: reachable. Store API /store/carts, payment collections
- Build customisations with an agent: reachable. medusa-agent-skills medusa-dev plugin; MCP server queries public docs only
- Manage Medusa Cloud resources: reachable. medusa-cloud plugin wraps the mcloud CLI (paid edition)

## Code stack

- Languages: TypeScript
- Frameworks: Node.js, Express, MikroORM, React (admin)
- Package manager: yarn
- Database: PostgreSQL, Redis
- Hosting target: Docker, Medusa Cloud, Railway/Render

## Skills

bundled: Medusa publishes a Claude Code plugin marketplace teaching an Adopter's agent storefront best practices and how to build on Medusa; the core repo separately carries contributor-only skills under .claude/skills/.
- Paths: plugins/ecommerce-storefront/skills/storefront-best-practices/SKILL.md, plugins/learn-medusa/skills/learning-medusa/SKILL.md
- Install: /plugin marketplace add medusajs/medusa-agent-skills

## Evidence and confidence

- formFactor: docs: Node.js server with admin dashboard; storefront separate (confidence 0.9)
- executionModel: no model at runtime (confidence 0.95)
- operability: docs.medusajs.com publishes Admin and Store API references; medusa-agent-skills under the medusajs org (confidence 0.9)
- effort: docs environment-variables page names 18 vars; medusa-config reference documents five sections (confidence 0.8)
- editions: LICENSE: MIT except Enterprise Edition; README: Medusa Cloud (confidence 0.7)
- active: pushedAt 2026-09-02
- reach:  (confidence 0.85)

## Open questions

- Medusa Cloud pricing
- medusa-agent-skills last commit date

## Sources

- https://github.com/medusajs/medusa (sourcing:ecommerce:community)
- https://github.com/medusajs/medusa-agent-skills (sourcing:ecommerce:community)
- https://docs.medusajs.com/resources/references/medusa-config (analysis)