Medusa.js Installation: Complete Headless Commerce Guide
Manual headless commerce setup often takes a whole day, and Redis configuration errors still appear. Medusa.js solves this: one CLI command deploys backend, admin, and storefront. We'll show how to install and configure Medusa 2.x correctly, with production requirements in mind.
What is Medusa.js and why do you need it?
Medusa.js is an open-source headless commerce platform on Node.js, an alternative to Shopify and Magento. Unlike monolithic solutions, Medusa gives full control over API and backend. You are not tied to templates—use any frontend (Next.js, Nuxt, React). Companies with a technical team choose Medusa for customizing business logic without platform limitations.
Why Medusa.js is more profitable than Shopify for a scalable store?
Shopify offers a quick start, but as your business grows, you hit limits: high transaction fees, inability to customize cart logic, vendor lock-in. Medusa offers flexibility: you control the code, pay no commission, and can integrate any payment system (Stripe, PayPal, YooKassa). According to tests, Medusa on your own servers costs 2-3 times less under loads of 10,000 orders per month. Savings on fees can reach $2,500 per month with $100,000 turnover.
| Criteria | Shopify | Medusa.js |
|---|---|---|
| Transaction fee | 2.9% + 30¢ (or less) | 0% |
| Backend customization | Limited | Full (Node.js) |
| Vendor lock-in | Yes (hard to migrate) | No (open source) |
| Hosting | Shopify only | Any (VPS, cloud) |
| Performance (LCP) | Average | High (SSR, cache) |
How to install Medusa.js in 5 minutes?
Medusa 2.x requires Node.js 20+, PostgreSQL 15+ and Redis 7+. The official CLI create-medusa-app deploys backend and optionally Next.js Storefront and Admin Dashboard with one command. According to official Medusa documentation, installation via CLI takes under 5 minutes.
Quick start
# Installation via official CLI npx create-medusa-app@latest mystore The interactive setup asks for project name, whether you need Next.js Storefront, whether you need Admin Dashboard, and the PostgreSQL connection string. If you're new to Medusa, choose everything to get a ready sandbox.
Manual installation and configuration
mkdir mystore && cd mystore npm init -y npm install @medusajs/medusa @medusajs/framework # Initialize structure npx medusa new . --skip-db # Environment variables cat > .env << 'EOF' DATABASE_URL=postgresql://medusa:password@localhost:5432/medusa_db REDIS_URL=redis://localhost:6379 JWT_SECRET=$(openssl rand -base64 32) COOKIE_SECRET=$(openssl rand -base64 32) STORE_CORS=http://localhost:8000 ADMIN_CORS=http://localhost:9000 AUTH_CORS=http://localhost:9000,http://localhost:8000 EOF # Apply migrations and seed initial data npx medusa db:create npx medusa db:migrate npx medusa user -e [email protected] -p AdminPass123 --invite # Start dev server npx medusa dev Admin Dashboard setup
# Admin — separate Vite project npm create @medusajs/admin-vite-plugin@latest medusa-admin cd medusa-admin npm install npm run dev # http://localhost:9000 How to configure Medusa for high load without performance loss?
Once we set up Medusa for an online store with 50,000 products and 20,000 orders per month. We started with a basic setup but faced performance issues due to N+1 queries when loading categories. Optimization via Redis caching and configuring async queue processing for product updates reduced TTFB from 2 seconds to 300 ms. Key steps include setting a PostgreSQL connection pool (e.g., 20 connections), enabling query caching via Redis, and using batch processing for bulk operations.
Common errors and solutions
- Redis connection error: check that Redis is running and the port is correct. Medusa does not work without Redis.
- Hydration mismatch in Storefront: if using Next.js, ensure server-side and client-side rendering are consistent.
- CORS errors: in .env correctly specify STORE_CORS, ADMIN_CORS, AUTH_CORS—otherwise the frontend cannot reach the API.
| Variable | Description |
|---|---|
| DATABASE_URL | PostgreSQL connection string |
| REDIS_URL | Redis connection string |
| JWT_SECRET | Secret for signing JWT |
| COOKIE_SECRET | Secret for signing cookies |
| STORE_CORS | Allowed origins for storefront |
| ADMIN_CORS | Allowed origins for admin |
| AUTH_CORS | Allowed origins for auth |
What is included in the setup work?
We don't just install packages—we prepare a production solution:
- Backend deployment on a dedicated server or in Docker containers.
- Integration with your database (migrations, seed, backups).
- Redis setup for caching and queues.
- Deployment of admin panel and storefront (Next.js, Nuxt).
- CORS, SSL, CI/CD configuration.
- Handover of full documentation and access.
- Team training on admin panel usage.
Work process
- Analysis — discuss requirements, load, select stack (Next.js vs Nuxt, database).
- Design — architecture: backend, microservices, Redis.
- Implementation — installation, configuration, module customization.
- Testing — load testing, Core Web Vitals check.
- Deployment — production deployment, monitoring setup.
- Support — 30-day warranty for uncovering hidden errors, SLA 4 hours.
Timelines and guarantees
Basic installation + environment setup + first run: 2 to 4 hours. Full production deployment with Docker, SSL, and CI/CD: up to 1 day. Timelines depend on customization complexity. Our experience: over 30 Node.js projects, we provide a 30-day warranty on uninterrupted operation after deployment. Each project undergoes security audit and load testing.
If you need a production Medusa.js deployment, contact us for a project evaluation. Get a consultation right now.