| name | ecommerce-builder |
| description | Full-stack ecommerce website builder for any physical product business. Creates production-ready online stores using Next.js 14+ (App Router), Medusa.js v2, Stripe + PayPal payments, Meilisearch, PostgreSQL, and cloud deployment (Vercel + Railway/Render). Supports ~1000+ SKUs with product variants (size, color, material) and multi-currency. Fully customizable: adapts store name, brand identity, product categories, and filtering attributes to the user's specific business. Modular design: 6 independent modules (init, backend, frontend, payments, search, deploy). TRIGGERS: ecommerce site, online store, shopping website, Shopify alternative, headless commerce, Medusa storefront, "sell X online", "build a store", "create a shop", product catalog, checkout flow, Stripe/PayPal payments setup, product search/filtering, ecommerce deployment. Even partial requests like "set up Stripe for my store" or "add PayPal" should use this skill.
|
Ecommerce Website Builder
Build production-ready ecommerce websites for any physical product business.
Architecture Overview
┌─────────────────────────────────────────────────────┐
│ FRONTEND │
│ Next.js 14+ (App Router) on Vercel │
│ Tailwind CSS + shadcn/ui │
│ SSR/SSG for SEO │
└──────────────────────┬──────────────────────────────┘
│ REST / API Routes
┌──────────────────────┴──────────────────────────────┐
│ BACKEND │
│ Medusa.js v2 on Railway/Render │
│ Admin Dashboard built-in │
│ PostgreSQL (Railway or Supabase) │
└───┬──────────┬──────────┬──────────┬────────────────┘
│ │ │ │
Stripe PayPal Meilisearch S3/R2 SendGrid
(cards) (wallet) (search) (images) (emails)
Tech Stack
| Layer | Technology | Purpose |
|---|
| Frontend | Next.js 14+ (App Router) | SSR/SSG, routing, React Server Components |
| Styling | Tailwind CSS + shadcn/ui | Responsive, accessible UI components |
| Backend | Medusa.js v2 | Ecommerce engine, admin dashboard, API |
| Database | PostgreSQL | Product data, orders, customers |
| Payments | Stripe + PayPal | Cards, Apple Pay, Google Pay, PayPal Checkout, USD/CAD |
| Search | Meilisearch | Fast product search, faceted filtering |
| Storage | AWS S3 / Cloudflare R2 | Product images, assets |
| Frontend Deploy | Vercel | Edge network, automatic previews |
| Backend Deploy | Railway / Render | Managed containers, auto-scaling |
| Email | SendGrid / Resend | Order confirmations, transactional emails |
Modular Execution
This skill is split into 6 independent modules. Execute them in order for a full build, or run individual modules to work on specific parts. Each module is self-contained with its own reference file containing detailed instructions.
How to use modules
When the user asks to build a full ecommerce site, execute modules 1 through 6 in sequence. When the user asks about a specific aspect (e.g., "set up Stripe payments"), jump directly to the relevant module.
Before starting any module, read its reference file from the references/ directory.
| Module | Name | Reference File | What It Builds |
|---|
| 1 | Project Initialization | references/module-1-init.md | Next.js scaffold, Tailwind, shadcn/ui, project structure, env template |
| 2 | Medusa Backend | references/module-2-medusa.md | Medusa v2 server, PostgreSQL, admin dashboard, product models |
| 3 | Frontend Core Pages | references/module-3-frontend.md | All storefront pages: home, catalog, product detail, cart, checkout, account |
| 4 | Payment System | references/module-4-payments.md | Stripe + PayPal integration, multi-currency, Apple/Google Pay, webhooks |
| 5 | Search & Products | references/module-5-search.md | Meilisearch, faceted filtering, CSV import, inventory management |
| 6 | Deploy & Security | references/module-6-deploy.md | Vercel + Railway deployment, SSL, security hardening, CI/CD |
Module Dependencies
Module 1 (Init) ─────► Module 2 (Medusa) ─────► Module 3 (Frontend)
│
├──► Module 4 (Payments)
├──► Module 5 (Search)
└──► Module 6 (Deploy)
Modules 4, 5, and 6 can be executed in any order after Module 3 is complete.
Execution Flow
Step 0: Gather Store Information (once, before any module)
Before starting the first module, ask the user for their store details (see Store Customization table above). Use these values throughout all modules. If the user says "just use defaults" or gives incomplete info, use the outdoor apparel example as fallback and confirm.
For each module:
- Read the reference file —
Read the relevant references/module-N-*.md file
- Adapt to user's store — Replace all placeholder values (
{{STORE_NAME}}, {{STORE_SLUG}}, brand colors, categories, attributes) with the user's actual store information collected in Step 0
- Confirm scope with user — Briefly explain what the module will create and ask if they want any customizations
- Generate code — Follow the reference file's instructions to produce all files, using the user's store info
- Verify — Run linting, type-checking, or build commands as appropriate
- Summarize — Tell the user what was created and what to do next
Key Design Decisions
These decisions reflect best practices for a ~1000 SKU ecommerce store:
Why Medusa.js v2 over Shopify/WooCommerce: Full control over the codebase, no transaction fees, extensible plugin system, and a modern API. For a business with 1000+ SKUs that needs custom filtering and multi-currency support, Medusa provides the flexibility that hosted platforms restrict.
Why Next.js App Router: React Server Components reduce client-side JavaScript, improving Core Web Vitals scores that directly impact Google Shopping rankings. The App Router's nested layouts map naturally to ecommerce page hierarchies (category → subcategory → product).
Why Meilisearch over Algolia: Self-hostable (no per-search pricing), typo-tolerant out of the box, and supports faceted search for complex product filtering (category, attributes, size, color, price range, etc.).
Why Stripe + PayPal: Stripe is the dominant card processor with native multi-currency, Apple Pay, and Google Pay support. PayPal adds a trusted wallet option that many shoppers prefer — especially for higher-value purchases where buyer protection matters. Offering both maximizes conversion by letting customers pay the way they're most comfortable.
Store Customization
This skill is fully customizable to any physical product business. Before starting Module 1, collect the following from the user:
| Parameter | Description | Example |
|---|
| Store Name | Brand name used throughout the site | "Summit Outfitters", "Bloom & Petal", "TechGear Pro" |
| Store Slug | URL-safe project name (auto-derived if not given) | summit-outfitters, bloom-and-petal |
| Product Categories | Top-level categories for the catalog | Jackets, Footwear, Accessories |
| Product Attributes | Custom filterable attributes beyond size/color/price | activity_type, material, flavor, roast_level, etc. |
| Target Markets | Countries/currencies to support | US (USD), Canada (CAD), EU (EUR) |
| Brand Colors | Primary/secondary/accent colors for Tailwind theme | forest green + cream, navy + gold, etc. |
| Brand Description | One-line tagline for SEO metadata | "Premium outdoor apparel and gear" |
Use these values to replace all placeholder values ({{STORE_NAME}}, {{STORE_SLUG}}, etc.) in the module reference files. If the user doesn't specify certain parameters, use sensible defaults and confirm with them.
Sample Data
The scripts/seed-sample-data.ts provides an example seed script for an outdoor apparel store. When building for a different business type, adapt the seed script to match the user's actual product categories, attributes, and pricing. The script structure (categories → products → variant matrix) is reusable for any product type.
Important Notes
- All code comments should be in English
- The storefront UI language is English (with i18n structure ready for future localization)
- Currency display follows the user's target market conventions
- Shipping and tax handling should be configured for the user's target markets (e.g., Stripe Tax, TaxJar, or Avalara)
- All environment variables go in
.env.local (never committed to git)
- The
.env.example template documents every required variable
