Shopify Ecommerce Development Workspace

A complete Shopify ecommerce development environment with two approaches: a traditional custom Shopify theme and a modern headless commerce solution.

🚀 Production Site

Live Demo: https://shopify-headless-lemon.vercel.app/

Features:

• ✅ Performance Excellence: 99.9% CLS reduction (25→0.028), 0ms Total Blocking Time (optimized from 680ms)
• ✅ Family Plan Builder with real-time pricing
• ✅ Shopping cart with Context API state management
• ✅ Product pages with Shopify integration
• ✅ AI Chatbot with ecommerce strategy (product search, recommendations)
• ✅ Cypress E2E testing (13+ tests)
• ✅ CI/CD with GitHub Actions + Vercel auto-deploy
• ✅ TypeScript type safety throughout

Architecture Highlights

✅ Performance Optimized

• SSR carousel (ssr: true)
• Inline critical CSS (1.3 KiB)
• Custom CSS only (no Tailwind)
• Dynamic imports

✅ React Architecture

• Server layout (metadata)
• Client wrapper (contexts)
• Proper hydration boundaries

📖 Family Plan Documentation

📁 Project Structure

This workspace contains two complete Shopify ecommerce implementations:

1. shopify-theme/ - Custom Shopify Theme

Traditional Shopify theme using Liquid templating, perfect for stores that want full Shopify admin integration and traditional theme customization.

Features:

• Complete Shopify theme structure (Liquid templates)
• Customizable sections and snippets
• Theme settings for easy customization
• Product, collection, and cart pages
• Responsive design

Current Status:

• Header and footer sections: not yet complete
• Collection pages: in progress
• Newsletter signup: not yet complete

→ View shopify-theme README

2. shopify-headless/ - Headless Next.js + Shopify

Modern headless commerce solution using Next.js, TypeScript, and Shopify Storefront API for maximum flexibility and performance.

Features:

• Next.js 14 with App Router
• TypeScript for type safety
• CSS Modules for component-scoped styling
• Shopify Storefront API integration
• Performance Optimized: Code splitting, dynamic imports, webpack optimization (CLS: 0.028, TBT: 0ms)
• Shopping cart with Context API
• AI Chatbot widget (Ecommerce strategy with GPT-4)
• Cypress E2E testing
• CI/CD with GitHub Actions
• Vercel auto-deploy
• Optimized performance and SEO
• Full control over frontend
• Docker containerization for reproducible dev, CI/CD, and onboarding

Current Status:

• Collections pages: complete
• AI chatbot integration: complete ✅
• Product search: in progress

→ View shopify-headless README

🚀 Quick Start

Option 1: Custom Shopify Theme

cd shopify-theme

# Install Shopify CLI
npm install -g @shopify/cli @shopify/theme

# Connect and start development
shopify theme dev --store your-store.myshopify.com

Option 2: Headless Next.js Store

cd shopify-headless

# Install dependencies
npm install

# Set up environment variables
cp .env.local.example .env.local
# Edit .env.local with your Shopify credentials

# Start development server
npm run dev

Option 3: Dockerized Development (Recommended for teams)

cd shopify-headless
# Build and run the container
# (Requires Docker Desktop)
docker build -t shopify-headless .
docker run -p 3000:3000 --env-file .env.local shopify-headless

🤔 Which Approach Should I Use?

Use Custom Shopify Theme if you:

• Want to use Shopify's native checkout
• Need Shopify admin theme customization
• Prefer working within Shopify's ecosystem
• Want merchants to customize via Shopify admin
• Are building for the Shopify Theme Store

Use Headless Next.js if you:

• Need complete frontend control
• Want modern React development experience
• Need custom routing and page structures
• Require advanced performance optimization
• Want to integrate with multiple data sources
• Need custom user experiences beyond Shopify's capabilities

📋 Prerequisites

For Shopify Theme:

• Shopify store (trial or paid account)
• Shopify CLI installed
• Node.js 18+

For Headless Next.js:

• Shopify store with Storefront API access
• Node.js 18+
• Shopify Storefront API access token

🛠️ Development Tools

Recommended VS Code Extensions:

• Shopify Liquid - Syntax highlighting and snippets for Liquid
• ES7+ React/Redux/React-Native snippets - For Next.js components
• TypeScript - TypeScript language support
• ESLint - Code linting
• Prettier - Code formatting
• Cypress - E2E testing support
• Docker - Containerized dev and test environments

📚 Documentation

• Shopify Theme Development
• Shopify Storefront API
• Next.js Documentation
• TypeScript Documentation
• Cypress Documentation
• Project Context - Complete project reference
• Deployment Guide

🎯 Project Status

Completed ✅

• Shopping cart functionality (Context API + cart page + E2E tests)
• Family Plan Builder (Liquid + React versions)
• Collections pages (listing + detail + breadcrumbs) — complete for Headless Storefront, in progress for Custom Theme
• Product images (11 products with Unsplash images)
• Product and collection management scripts (create, publish, delete, test, images)
• Vercel auto-deploy configuration
• CI/CD with GitHub Actions + Cypress
• TypeScript type safety
• Production deployment: https://shopify-headless-lemon.vercel.app/

In Progress 🚧

• Jest/React Testing Library unit tests
• Storybook component library
• Product search functionality (Headless Storefront, in progress)
• Docker containerization for local dev, CI/CD, and onboarding (planned)

See ROADMAP.md for complete development plan

🎯 Next Steps

1. View Live Site: Visit https://shopify-headless-lemon.vercel.app/
2. Run Locally: cd shopify-headless && npm install && npm run dev
3. Run Tests: npm run test:e2e (Cypress E2E tests)
4. Read Documentation: Check PROJECT_CONTEXT.md for setup details
5. Start Development: Follow CONTRIBUTING.md for workflow

🆘 Getting Help

• Shopify Community Forums
• Shopify Dev Discord
• Next.js Discord

📄 License

MIT License - Free to use for your projects!

---

Happy Building! 🎉

Start with either shopify-theme/ or shopify-headless/ directory and follow their respective README files for detailed setup instructions.