You're paying $299 a month for a Shopify Advanced plan, and half the features you're billed for are ones you've never clicked. Sound familiar? That was me three years ago — staring at an invoice and wondering whether the platform was working for my store or the other way around.
Medusa.js has been quietly gaining ground as a legitimate open-source alternative for store owners who want to own their stack. It's not a hosted SaaS, which means no monthly platform tax, no revenue-share surprises, and no waiting on a third party to ship the feature you actually need. The trade-off is that you do a bit more setup work upfront. But "a bit more" is genuinely a weekend's worth — not a six-month engineering project — and this tutorial will walk you through every step.
What Medusa.js Actually Is (30-Second Version)
Medusa is a headless commerce engine: a Node.js backend that handles your products, orders, customers, and payments through a REST API. "Headless" just means the storefront — the part your customers see — is a separate app you build however you like. React, Next.js, plain HTML, a mobile app — Medusa doesn't care.
The backend ships with:
- Product and inventory management
- Cart and checkout logic
- Built-in support for Stripe, PayPal, and manual payments
- A plugin system for shipping carriers, CMS tools, and search
- An admin dashboard at zero extra cost
For comparison, Shopify's comparable headless offering (Hydrogen + Oxygen) locks you into their hosting and charges starting at $2,000/month for Plus. Medusa runs on any $6/month VPS or a free Railway.app hobby tier while you're testing.
What You'll Need Before You Start
Let's be honest about prerequisites so you don't hit a wall on Saturday afternoon.
You'll need:
- Node.js 18+ installed on your machine (nodejs.org, five-minute install)
- A free account on Railway.app or Render.com for hosting the backend
- A Stripe account for payments (free to create, you only pay per transaction)
- Basic comfort with a terminal — copy-paste level is fine
- About 6–8 focused hours split across two days
You do not need to be a developer. I've helped three non-technical store owners get through this setup. The Medusa CLI does the heavy lifting.
Day One: Spin Up the Backend (3–4 Hours)
Install and scaffold
Open your terminal and run:
npx create-medusa-app@latest my-store
The CLI will ask a few questions — pick the default Next.js storefront when prompted. It installs both the backend and a starter storefront in one shot. On a decent internet connection this takes about four minutes.
Once it finishes, you'll have two folders: my-store (the Medusa backend) and my-store-storefront (the Next.js frontend). Navigate into the backend folder and start the server:
cd my-store
medusa develop
Visit http://localhost:9000/health and you should see {"status":"ok"}. That's your commerce engine running locally. Go ahead and feel good about that — it took me three days to get this far on my first headless build in 2021 because the tooling wasn't nearly this smooth.
Create your admin account
The first time you run medusa develop, it seeds a default admin user. Open http://localhost:7001 in your browser to reach the admin dashboard. Log in, poke around — you'll recognize it immediately. Add a product with a price and a couple of variants. This is where you'll manage your catalog day-to-day, so it's worth spending 30 minutes getting comfortable.
Connect Stripe
In your my-store folder, open .env and add your Stripe secret key:
STRIPE_API_KEY=sk_test_...
Then install the Stripe plugin:
npm install medusa-payment-stripe
Add it to medusa-config.js under plugins. The Medusa docs have a copy-paste snippet for this — it's literally four lines. Restart the server, go to Settings → Regions in the admin, and enable Stripe for your region. Done. You now have a working payment processor.
Push the backend to Railway
Railway.app has a one-click deploy template for Medusa. Go to railway.app/new, search "Medusa", and connect your GitHub repo (you'll need to push your local folder first with git init && git push). Railway provisions a PostgreSQL database automatically and wires the environment variables. Total time: about 20 minutes including the GitHub push.
At the end of Day One you have a live, hosted commerce backend with real products and Stripe payments. That's the hard part — and it's done.
Day Two: Wire Up the Storefront (2–3 Hours)
The Next.js storefront the CLI generated is functional but generic. Here's how to make it yours without touching much code.
Point the storefront at your live backend
Open my-store-storefront/.env.local and update:
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-railway-url.up.railway.app
Start the storefront locally:
cd my-store-storefront
npm run dev
Visit http://localhost:8000. You should see the products you added yesterday. Click one, add it to cart, go through checkout with a Stripe test card (4242 4242 4242 4242). Watch the order appear in your admin dashboard in real time. That moment — seeing an end-to-end order flow on infrastructure you control — is genuinely satisfying.
Customize the look without rewriting everything
The starter storefront uses Tailwind CSS. You don't need to redesign it from scratch. Three changes cover 80% of the visual work:
- Colors — Edit
tailwind.config.jsand swap the primary color values to match your brand hex codes. One file, five minutes. - Logo — Drop your logo file into
/publicand update the<Logo />component reference insrc/modules/layout/components/nav/index.tsx. - Hero banner — The homepage hero is in
src/modules/home/components/hero/index.tsx. Replace the placeholder text and background image with your own.
These three edits alone make the storefront look intentional rather than template-y. You can go deeper later — custom product page layouts, a blog section, a size guide modal — but ship first, polish second.
Deploy the storefront
Vercel is the easiest option for a Next.js frontend. Connect your storefront repo at vercel.com/new, add the NEXT_PUBLIC_MEDUSA_BACKEND_URL environment variable, and deploy. Vercel's free tier handles up to 100GB of bandwidth per month, which is plenty for a store doing under $50K/month in revenue.
Your full stack now costs:
- Medusa backend on Railway: $5–$10/month (hobby tier)
- Storefront on Vercel: $0 (free tier)
- Stripe: 2.9% + $0.30 per transaction, no monthly fee
- Total fixed cost: under $10/month
Compare that to $299/month for Shopify Advanced plus $15–$30/month in apps you've bolted on. For a store doing $10K/month, you're looking at saving $285+ every single month.
A Real-World Example: The Candle Store
A reader named Priya runs a small soy candle brand. She was on Shopify at $79/month, paying an extra $19/month for a subscription app and $29/month for a review app. That's $127/month before transaction fees.
She followed this exact setup over a long weekend. Her backend runs on Railway's $5 plan. For reviews, she dropped in a free Trustpilot widget. For subscriptions, she's evaluating Medusa's native subscription plugin (still beta, but functional for simple recurring orders).
Her current fixed stack cost: $5/month. She reinvested the $122/month savings into Facebook ads. In the first 90 days after switching, her revenue went up 18% — not because Medusa is magic, but because she stopped bleeding money on platform fees and put it to work.
Is Medusa right for every store? No. If you're doing less than $2K/month and the thought of a terminal makes you sweat, Shopify's $39 Basic plan is genuinely a fine choice. The math only tips toward Medusa once you're paying for features you don't use or scaling toward a custom storefront experience anyway.
Three Things to Do Right After You Launch
Once your store is live, don't stop at "it works." These three moves will save you headaches later:
-
Set up automated database backups. Railway has a one-click backup schedule under your PostgreSQL service settings. Enable daily backups. Takes 90 seconds and protects your order history.
-
Add a CDN in front of your images. Medusa stores product images locally by default. Install the
medusa-file-s3plugin and point it at an AWS S3 bucket (or Cloudflare R2 if you want zero egress fees). Your page load times will thank you. -
Connect your transactional email. Out of the box, Medusa sends order confirmations through a basic SMTP setup. Swap in SendGrid or Resend (both have free tiers up to 3,000 emails/month) using the
medusa-plugin-sendgridormedusa-plugin-resendpackages. Branded order emails build trust faster than almost anything else you can do in week one.
You're More Ready Than You Think
Headless commerce sounds intimidating until you actually do it. The Medusa CLI, Railway's one-click deploys, and Vercel's zero-config Next.js hosting have genuinely collapsed what used to be a week of DevOps into a couple of focused afternoons.
You don't need to be a full-stack engineer. You need a weekend, a terminal window, and the willingness to follow steps in order. Thousands of small stores are already running on this stack — yours can be next.
Your immediate next step: run npx create-medusa-app@latest right now, even just locally, and spend 20 minutes clicking around the admin. You'll see exactly how close "ready to sell" really is.