ecommerce-builder

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:

1. Read the reference file — Read the relevant references/module-N-*.md file
2. 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
3. Confirm scope with user — Briefly explain what the module will create and ask if they want any customizations
4. Generate code — Follow the reference file's instructions to produce all files, using the user's store info
5. Verify — Run linting, type-checking, or build commands as appropriate
6. 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