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

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 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:

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