🌍 LanguageShop – Merch Store for Language Schools

LanguageShop is a modern, responsive Progressive Web App (PWA) built with React 19, React Router v7, and Vite. It simulates an online merchandise store for a language school, featuring hoodies, t-shirts, mugs, and more — all powered by mocked data.

---

✨ Features

• 🛍️ Product Catalog: Hoodies, zip-up hoodies, t-shirts, mugs, and socks
• 🔍 Smart Filtering: By category, price range, size, color, and availability
• 🛒 Shopping Cart: Add, update quantity, remove — with localStorage persistence
• 📱 Fully Responsive: Mobile-first design that works on all screen sizes
• 📥 Offline Support: PWA with service worker caching for UI and product data
• 🧪 Comprehensive Testing: Unit, integration, and E2E tests with Vitest + Playwright
• 🧼 Clean Code: Built with SOLID, DRY, and KISS principles
• 📦 Zero Backend: Full REST API simulation using MSW (Mock Service Worker)
• 📝 Conventional Commits: Use Conventional Commits for commit messages

---

🚀 Quick Start

Prerequisites

• Node.js 20+
• pnpm 10+

Installation

1. Clone the repository:

   git clone https://github.com/gsroka/languageshop.git
   cd languageshop

2. Install dependencies:

   pnpm install

3. Start the development server:

   pnpm dev

4. Open your browser:
   Navigate to http://localhost:5173

💡 No environment setup needed! All data is mocked — no API keys or .env files required.

---

🛠️ Tech Stack

• Framework: React 19 with useOptimistic, useActionState
• Routing & SSR: React Router v7
• Bundler: Vite 7 for lightning-fast HMR
• State Management: Zustand 5.x — minimal, typed, scalable
• Styling: Tailwind CSS v4
• Forms: React Hook Form v8 + Zod
• API Mocking: MSW (Mock Service Worker)
• PWA: vite-plugin-pwa
• Testing: Vitest, React Testing Library, Playwright
• Language: TypeScript 5.5
• Tooling: ESLint, Prettier

---

📁 Project Structure (React Router v7)

language-shop/
├── app/                        # Main application directory (replaces src/)
│   ├── routes/                 # File-based routing (e.g., routes.products.$id.tsx)
│   ├── components/             # Shared UI and feature components
│   │   ├── ui/                 # Button, Input, Badge
│   │   ├── layout/             # Header, Footer, Root layout
│   │   └── features/           # ProductCard, CartItem, FilterPanel
│   ├── hooks/                  # useDebounce, useLocalStorage
│   ├── stores/                 # Zustand stores (cart, products, filters)
│   ├── types/                  # TypeScript interfaces (Product, CartItem)
│   ├── utils/                  # formatters, helpers
│   ├── app.css                 # global styles
│   └── root.tsx                # app root
├── public/                     # Static assets, PWA manifest, icons
│   └── manifest.webmanifest
├── tests/                      # Unit & integration tests
├── e2e/                        # Playwright E2E tests
├── vite.config.ts              # Vite + PWA config
└── tsconfig.json               # With path alias: ~ → app/

---

🧼 Engineering Principles

This project strictly follows modern software engineering best practices:

• SOLID: Each store and component has a single responsibility.
• DRY: Shared types, hooks, and UI components are reused across the app.
• KISS: No over-engineering — logic lives only where necessary.
• Conventional Commits: All commits follow the Conventional Commits 1.0.0 spec.

Example commits:

feat(cart): persist cart state in localStorage
fix(products): handle missing image with fallback
refactor(filters): extract price range logic to custom hook

---

📝 Scripts

pnpm dev          # Start dev server (Vite + React Router)
pnpm build        # Build for production (SSR + PWA-ready)
pnpm start        # Start production server
pnpm preview      # Preview production build locally
pnpm lint         # Run ESLint
pnpm format:write # Format code with Prettier
pnpm typecheck    # Run TypeScript checks
pnpm test         # Run Vitest (unit + integration)
pnpm test:e2e     # Run Playwright E2E tests

---

🗺️ Development Roadmap (TODO Phases)

View Full Implementation Plan

Phase 0: Project Setup & Configuration ✅

• Initialize project with pnpm create react-router@latest
• Install vite-plugin-pwa for PWA support
• Configure shadcn/ui
• Set up tsconfig.json with path alias ~/
• Create README.md with project overview
• Initialize Git + Conventional Commits

Phase 1: Architecture, Routing & Typing

• Define core types: Product, CartItem, ProductVariant
• Create folder structure inside app/: components/, types/, etc.
• Implement root layout (app/root.tsx)
• Set up routes: /, /products/:id, /cart, /checkout
• Add loading and error boundaries (React Router v7 conventions)
• Create shared layout components: Header, Footer

Phase 2: Mock API with MSW

• Install MSW
• Create mock product data (5 categories, 20+ items)
• Implement GET /api/products and GET /api/products/:id
• Integrate apiClient abstraction in app/api/client.ts
• Add delay and error simulation in MSW

Phase 3: Product Catalog & Filtering

• Build ProductList and ProductCard components
• Implement useProductStore with Zustand (fetch + cache)
• Create FilterPanel with React Hook Form + Zod
• Add search, category, price, size, color, availability filters
• Connect filters to product store via useFilterStore

Phase 4: Shopping Cart (Zustand + localStorage)

• Create useCartStore with persistence via Zustand persist
• Implement addToCart, updateQuantity, removeFromCart
• Build CartPage with editable items
• Add cart badge in Header

Phase 5: Product Detail Page

• Create dynamic route app/routes/products.$id.tsx
• Fetch product by ID
• Display variants (size, color), image gallery, description
• Add “Add to Cart” button with variant selection

Phase 6: Checkout Flow (Mock)

• Build CheckoutPage with contact form (RHF + Zod)
• Validate name, email, address
• Show order summary
• On submit: show success modal, clear cart

Phase 7: PWA & Offline Support

• Configure vite-plugin-pwa to cache routes and API
• Add an offline fallback page
• Test offline mode in DevTools

Phase 8: Testing

• Unit tests for Zustand stores (Vitest)
• Component tests (RTL): ProductCard, Cart
• E2E test: add to cart → checkout (Playwright)

Phase 9: Polish & Performance

• Lazy-load images (loading="lazy")
• Optimize re-renders (React.memo, useCallback)
• Add meta tags, favicon, PWA icons
• Lighthouse audit → fix accessibility/performance

---

📧 Contact

Grzegorz Sroka - @gsroka89

Project Link: https://github.com/gsroka/languageshop