Next.js App Router storefront including a homepage, /shop and /shop/[slug] product pages, cart, and multi-step checkout
Next.jsReactE-commerceStarter
medusa-nextjs-ecom-kit — Next.js Ecommerce Template
By floating-astronaut
An open-source headless e-commerce starter kit built on a Medusa 2.x backend and the Next.js App Router, already including a product catalog, cart, multi-step checkout, customer accounts, order emails, and optional analytics tracking, written in TypeScript and Tailwind CSS.
Explore the design
Compare the page layouts and mobile experience. Open any screenshot for a closer look.
Desktop homepage1 / 2
Desktop captureTop of page
Actual screenshot captured by the server browser.
All pages & views 2
Screenshots show visual appearance; interactive behavior may differ.
Recorded 2026-10-15View source
What stands out
A quick read of the recorded project description.
Medusa 2.x headless backend that manages products, variants, pricing, inventory, and regions, and provides an admin dashboard
Customer account area /account/* with registration, login, profile, and order history
Transactional emails for each order stage (placed, paid, shipped, delivered, canceled), integrated with any SMTP service via Nodemailer
Environment-variable-driven brand configuration, with name, color scheme, currency, social links, and policy copy centralized in brand.ts
Built-in SEO-related output: metadata, JSON-LD, sitemap.xml, robots.txt, and llms.txt
Template Details
This template is a headless e-commerce starter kit with a Next.js App Router storefront on the front end, Medusa 2.x on the back end, and PostgreSQL as the database. The README states that it already wires up the product catalog, cart, multi-step checkout, customer registration/login and order history, transactional emails for each order stage, and optional Google Analytics and Meta Pixel / Conversions API. Brand information (name, color scheme, currency, social links, policy copy) is driven by environment variables and src/config/brand.ts, so most appearance changes require no code edits.
The checkout section provides two paths that are independent of any payment provider: bank transfer is a manual payment flow that generates a payment reference after ordering and sends an email; the placeholder (demo) payment route marks the order as paid and redirects to a success page, and the README explicitly states that it does not produce a real charge and cannot be used for real payments. To integrate real payments, you need to replace the placeholder implementation in src/app/api/payments/ and integrate the chosen payment provider on the server side.
The README does not provide information on performance, concurrency, security hardening, or production operations; the template ships with neutral placeholder branding and product data that you need to replace yourself.
Next.jsReactE-commerceStarter
Is it right for your project?
Use Cases
- You need a runnable headless e-commerce starting point rather than building product, cart, and checkout flows from blank pages
- You want to manage products, inventory, and regions with Medusa and build a custom storefront with Next.js
- You need customer accounts and order history, and automatic emails for each order stage
- You want to run the complete ordering flow with bank transfer or demo payment before integrating a real payment provider
- You want to quickly replace brand information via environment variables and use the same codebase for different stores
Suitable For
- Developers familiar with Next.js and TypeScript who want to build their own storefront
- Teams planning to use Medusa as a headless e-commerce backend
- Those who need a neutral starter project where the payment and email providers can be replaced independently
- Developers willing to prepare PostgreSQL themselves and complete deployment according to the README
Getting started & customization
Use these recorded setup notes alongside the repository instructions for your chosen version.
- 1
Prerequisites: Node 20+, a PostgreSQL database, and optionally Redis
- 2
Backend: enter the medusa/ directory, copy .env.template to .env and fill in DATABASE_URL and other values, run npm install, npx medusa db:migrate, npm run seed, npm run dev; Medusa runs on port 9000, and the admin dashboard is at /app
- 3
Frontend: at the repository root, copy .env.example to .env.local, fill in MEDUSA_PUBLISHABLE_KEY and MEDUSA_REGION_ID obtained from the Medusa admin dashboard, run npm install and npm run dev; the storefront runs on port 3000
- 4
build-all.sh can build both the backend and frontend at once
- 5
Payments: bank transfer is a manual flow; the placeholder (demo) route does not produce a real charge, and integrating real payments requires replacing the placeholder implementation in src/app/api/payments/
License & source material
Usage conditions & limitations
Free to use · keep license noticeThis listing covers the free version under the MIT license in the public repository; the free scope is the code of that version and does not mean that external services or third-party assets are free.
Must comply with when using
- You may use, modify, commercialize, and distribute the code of this version for free.
- When distributing copies or substantial portions of the code, retain the original author's copyright notice and the complete MIT license notice.
- The code is provided as is; warranties and limitations of liability are governed by the original license and applicable law.
Additional costs & items to verify
- Demo images, fonts, icons, and other third-party assets must be checked against their respective licenses and cannot be judged solely by the code's MIT license.
- External services such as domains, hosting, databases, payments, or AI may incur separate charges.
- The placeholder (demo) payment route is for demonstration only, does not produce a real charge, and cannot be used for real payments; integrating real payments requires replacing the placeholder implementation yourself.
- The checkout flow can be completed without registering any payment service, but real payments require integrating a payment provider yourself.
- Running requires Node 20+ and a PostgreSQL database, with Redis optional.
- You need to obtain MEDUSA_PUBLISHABLE_KEY and MEDUSA_REGION_ID from the Medusa admin dashboard and fill them into .env.local.
- The template ships with neutral placeholder branding and product data that you need to replace with actual content.
- Google Analytics and Meta Pixel / Conversions API analytics tracking are optional features.
View Original Text Basis
Permission is hereby granted, free of charge
Original License Text
**No real charge — do not use it to take real money.**
Original README
runnable **without signing up for anything**:
Original README
**Prerequisites:** Node 20+, a PostgreSQL database, and (optionally) Redis.
Original README
Get `MEDUSA_PUBLISHABLE_KEY` and `MEDUSA_REGION_ID` from the Medusa admin
Original README
> This template ships neutral placeholder branding and products for you to
Original README
https://github.com/floating-astronaut/medusa-nextjs-ecom-kit/blob/main/LICENSEhttps://github.com/floating-astronaut/medusa-nextjs-ecom-kit/blob/main/README.md| 📈 **Analytics** | Optional Google Analytics + Meta Pixel / Conversions API |
Original README
Compiled by DeepSeek based on repository license and README ·2026-10-15. Results only cover the materials read; dependencies, images, fonts, and subsequent term changes are subject to their respective original texts.
Project checks & description sources
Template Information
- Source platforms
- GitHub
- Documentation and maintenance reference score
- More documented · 88 / 100
- Technologies
- Next.js · React
- Website type
- E-commerce · Starter
How this score is calculated
Our heuristic uses license records (up to 30), a demo link (12), a preview (10), stars (15), recorded maintenance (15), description completeness (8), feature records (5) and classification data (5). It is not a code, security or performance test, or a Google score. A link does not establish tested functionality.
What to verify for this project
- Repository update recorded
- 2026-10-05
- Screenshot last checked
- 2026-10-15
A demo link is listed. Check it with your own content and viewport sizes; its presence does not confirm that forms, authentication or payments work.
The catalog identifies Next.js as the primary stack. Check the actual dependency manifest and lockfile for versions and hosting requirements. These notes use recorded metadata, not a code audit or a deployment test.
Use a selection guide →How this description was prepared
AI-assisted description based on catalog records and repository material. Repository authors are not automatically the reviewers of this description.
Review declaration: codex-user-requested-batch-review-20261015 · 2026-10-15
Inspect the recorded source material
SHA-256: 60a6e93add8b1b88c3d0b40aac58dede5fe3bf3911b588a6dcdd27a53a9330d1
2026-10-15T00:18:46.626Z
Source file / repository<div align="center">
# Medusa + Next.js E-commerce Kit
### An open-source, production-shaped headless commerce starter — a **Next.js 16** storefront on a **Medusa 2.x** backend.
Cart, checkout, customer accounts, order history, product catalog, transactional
email, and analytics — already wired together, so you start from a working store
instead of a blank page.
[](https://nextjs.org/)
[](https://react.dev/)
[](https://medusajs.com/)
[](https://www.typescriptlang.org/)
[](https://tailwindcss.com/)
[](https://www.postgresql.org/)
[](./LICENSE)
[](#contributing)
**🔗 Live demo:** **[exotic420budz.com](https://exotic420budz.com/)** — a real store running on this exact stack.
</div>
---
## Table of contents
- [Why this kit](#why-this-kit)
- [Features](#features)
- [Architecture](#architecture)
- [Tech stack](#tech-stack)
- [Quick start](#quick-start)
- [Checkout & payments](#checkout--payments)
- [Project structure](#project-structure)
- [Make it yours](#make-it-yours)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [License](#license)
---
## Why this kit
Most headless-commerce tutorials stop at "hello products". This one ships the
parts that are actually annoying to build: a real multi-step **checkout**, a
**customer account** area with order history, **transactional email** for every
order stage, an **analytics** layer, and env-driven **branding** so one codebase
can become any store. It is intentionally provider-agnostic — swap in Stripe,
PayPal, or any gateway when you're ready to take money.
> This template ships neutral placeholder branding and products for you to
> replace with your own.
---
## Features
| | |
|---|---|
| 🛍️ **Storefront** | Home, catalog (`/shop`, `/shop/[slug]`), cart, and a multi-step checkout |
| 👤 **Customer accounts** | Register, login, profile, and order history (`/account/*`) |
| 💳 **Checkout & payments** | Generic **bank-transfer** flow + a **placeholder (demo)** payment route — provider-agnostic |
| 📧 **Transactional email** | Order-received, payment, shipped, delivered & canceled emails via any SMTP provider |
| 🎨 **Env-driven branding** | Name, colours, currency, socials & policy copy in one `brand.ts` — no code edits |
| 🔎 **SEO out of the box** | Metadata, JSON-LD, `sitemap.xml`, `robots.txt`, and `llms.txt` |
| 📈 **Analytics** | Optional Google Analytics + Meta Pixel / Conversions API |
| 🧱 **Headless backend** | Medusa 2.x: products, variants, pricing, inventory, regions, admin dashboard |
| 🧑💻 **Typed end-to-end** | TypeScript everywhere, `tsc --noEmit` clean |
---
## Architecture
```mermaid
flowchart LR
subgraph Client["🌐 Browser"]
U["Shopper"]
end
subgraph Storefront["▲ Next.js 16 storefront"]
direction TB
Pages["App Router pages<br/>shop · cart · checkout · account"]
API["Route handlers<br/>/api/orders · /api/payments · /api/webhooks"]
end
subgraph Backend["🟣 Medusa 2.x backend"]
direction TB
Store["Store & Admin API"]
Admin["Admin dashboard"]
end
DB[("🐘 PostgreSQL")]
Mail["✉️ SMTP / email"]
Analytics["📈 GA · Meta Pixel"]
U --> Pages
Pages --> API
Pages -->|products, cart| Store
API -->|draft orders, payments| Store
Store --> DB
Admin --> DB
API --> Mail
Pages --> Analytics
```
---
## Tech stack
| Layer | Technology |
|---|---|
| Storefront | Next.js 16 (App Router) · React 19 · TypeScript 5 |
| Styling | Tailwind CSS 4 |
| Backend | Medusa 2.13 (headless commerce) |
| Database | PostgreSQL |
| Email | Nodemailer (any SMTP / transactional provider) |
| Tooling | ESLint 9 · Corepack / pnpm (backend) · npm (storefront) |
---
## Quick start
**Prerequisites:** Node 20+, a PostgreSQL database, and (optionally) Redis.
```bash
# 1. Backend (Medusa) — in the medusa/ folder
cd medusa
cp .env.template .env # fill in DATABASE_URL etc.
npm install
npx medusa db:migrate
npm run seed # loads the placeholder catalog
npm run dev # Medusa on http://localhost:9000 (admin at /app)
# 2. Storefront (Next.js) — in a second terminal, from the repo root
cp .env.example .env.local # set MEDUSA_* keys from your Medusa instance
npm install
npm run dev # storefront on http://localhost:3000
```
Get `MEDUSA_PUBLISHABLE_KEY` and `MEDUSA_REGION_ID` from the Medusa admin
(**Settings → Publishable API Keys**, and **Settings → Regions**) and paste them
into `.env.local`.
> 💡 `build-all.sh` builds both the backend and the storefront in one shot.
---
## Checkout & payments
The kit ships two provider-agnostic payment paths so checkout is complete and
runnable **without signing up for anything**:
- **Bank Transfer** — a manual-payment flow. The order is created, a payment
reference is generated, and the customer is emailed account details to
complete the transfer.
- **Placeholder (Demo)** — creates the order and marks it paid via
`/api/payments/placeholder`, then lands on `/checkout/success`.
**No real charge — do not use it to take real money.**
```mermaid
sequenceDiagram
actor C as Shopper
participant SF as Next.js checkout
participant O as /api/orders
participant P as /api/payments/placeholder
participant M as Medusa backend
participant E as Email
Note over C,E: Bank Transfer flow
C->>SF: Choose "Bank Transfer"
SF->>O: POST order (bank_transfer)
O->>M: Create draft order
O->>E: Email payment reference + details
O-->>SF: paymentReference, payToEmail
SF-->>C: Show bank-transfer instructions
Note over C,E: Placeholder (Demo) flow
C->>SF: Choose "Placeholder (Demo)"
SF->>O: POST order (placeholder)
O->>M: Create draft order
SF->>P: POST { storefrontOrderId }
P->>M: Convert draft → order, mark paid
P-->>SF: ok
SF-->>C: Redirect to /checkout/success
```
### Going live
Replace the placeholder in [`src/app/api/payments/`](src/app/api/payments/) with
your provider of choice. Medusa has first-party support for Stripe and others;
wire the provider **server-side** and point the checkout's payment step at it.
Search the code for `PAYMENT_PROVIDER` and the `placeholder` payment route for
the seams.
---
## Project structure
```
.
├── src/ # Next.js storefront (App Router)
│ ├── app/ # routes: shop, cart, checkout, account, content, api/
│ ├── components/ # UI components
│ ├── config/brand.ts # env-driven brand config (single source of truth)
│ ├── data/ # product fetch/shape helpers
│ └── lib/ # medusa client, mailer, shipping, payment helpers
├── medusa/ # Medusa 2.x backend
│ └── src/
│ ├── api/ # custom API routes
│ ├── modules/ # custom modules
│ ├── subscribers/ # event subscribers (order lifecycle → email)
│ ├── workflows/ # custom workflows
│ └── scripts/seed.ts # placeholder catalog seed
├── public/ # static assets / images
├── scripts/ # ops helpers (deploy, stale-draft cleanup)
├── build-all.sh # build backend + storefront
└── .env.example # storefront env template
```
---
## Make it yours
| To change… | Edit |
|---|---|
| Store name, tagline, colours, currency, socials | `.env.local` / `.env` (see [`src/config/brand.ts`](src/config/brand.ts)) |
| Products | Medusa admin, or [`medusa/src/scripts/seed.ts`](medusa/src/scripts/seed.ts) |
| Home / about / FAQ / policies copy | `src/app/*/page.tsx` |
| Logo & imagery | `public/` |
| Payment provider | [`src/app/api/payments/`](src/app/api/payments/) |
Branding is intentionally env-driven — for most cosmetic changes you only touch
`.env`, no code.
---
## Deployment
- **Storefront** — deploys to any Node host or Vercel. Set the same env vars
from `.env.example` in your host's dashboard.
- **Backend** — deploy Medusa to any Node host with a managed PostgreSQL (and
optional Redis). See the [Medusa deployment docs](https://docs.medusajs.com/deployments).
- Point the storefront's `MEDUSA_BACKEND_URL` at your deployed backend.
---
## Contributing
Issues and PRs are welcome. Please keep changes typed (`npx tsc --noEmit` must
stay clean) and run `npm run lint` before opening a PR. See
[CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
---
## License
[MIT](./LICENSE) © Tejas Karan Agrawal. Use it, fork it, ship your store.
---
<div align="center">
*Built from a real, live storefront and opened up as a starting point.*
**If it saved you time, a ⭐ is appreciated.**
</div>
Explore similar templates
Compare previews and descriptions within the same stack and category.
Next.js SaaS Starter
The official Next.js SaaS starter template, integrating email/password authentication, Stripe Checkout subscriptions, a dashboard with user/team CRUD, basic Owner/Member RBAC, and activity logging.
Next.js · SaaS
Next.js Commerce
Vercel's officially maintained Next.js App Router ecommerce starter with deep Shopify integration, offering a complete product catalog, cart, and checkout flow. Core logic is modular for swapping backends, and community provider versions exist for BigCommerce, Medusa, and Saleor.
Next.js · E-commerce
Next-js-Boilerplate
A developer-first Next.js 16 starter with Tailwind CSS 4 and TypeScript, supporting both App Router and Page Router.
Next.js · Starter
tailwind-nextjs-starter-blog
A Next.js and Tailwind CSS blog starter template using Contentlayer for Markdown/MDX, with built-in SEO, code highlighting, and tags. It targets personal technical blogs and migration from Jekyll/Hugo to React, and supports one-click Vercel deployment.
Next.js · Blog
next-forge
next-forge is a Turborepo-based Next.js template maintained by Vercel, positioned as a starting point for SaaS products.
Next.js · Starter
SaaS-Boilerplate
SaaS-Boilerplate is an open-source SaaS starter template built with Next.js App Router, React 19, TypeScript, Tailwind CSS, and Shadcn UI.
Next.js · SaaS