Valkey E-Commerce Demo

An e-commerce platform starter built with React, designed to showcase Valkey capabilities across multiple subsystems. Created for the Build Beyond Limits hackathon powered by Valkey, hosted by React Hyderabad.

Overview

This project provides a fully-featured e-commerce frontend that teams can extend with Valkey-powered backend services including authentication, search, caching, real-time recommendations, and more.

Tech Stack

Frontend:

• React 18 (Create React App)
• React Router v6
• Bootstrap 5 + SCSS
• Phosphor Icons, React Slick, AOS animations

Backend (to be implemented by teams):

• Valkey Bundle (all modules included)

Prerequisites

• Node.js (v16 or higher recommended)
• npm (comes with Node.js)
• Docker (for running Valkey)

Getting Started

1. Clone the repository

git clone https://github.com/opensource-for-valkey/valkey-ecommerce-demo.git
cd valkey-ecommerce-demo

2. Start Valkey

Pull and run the Valkey bundle image which includes all modules:

docker pull valkey/valkey-bundle:9-alpine
docker run -d --name valkey -p 6379:6379 valkey/valkey-bundle:9-alpine

3. Install frontend dependencies

cd frontend
npm install

4. Run the frontend

npm start

The app will be available at http://localhost:3000.

Running Tests

The frontend uses Jest and React Testing Library (included with Create React App).

cd frontend

# Run tests in watch mode (interactive)
npm test

# Run tests once (CI mode)
CI=true npm test

# Run tests with coverage report
CI=true npm test -- --coverage

Building for Production

cd frontend
npm run build

This creates an optimized production build in the frontend/build folder.

Project Structure

valkey-ecommerce-demo/
├── frontend/                  # React application
│   ├── public/
│   │   └── assets/           # Static CSS, JS, images
│   ├── src/
│   │   ├── components/       # Reusable UI components (header, footer, cards, etc.)
│   │   ├── helper/           # Utility components (animations, preloader, scroll)
│   │   ├── pages/            # Page-level components
│   │   │   ├── HomePageOne.jsx
│   │   │   ├── ShopPage.jsx
│   │   │   ├── CartPage.jsx
│   │   │   ├── CheckoutPage.jsx
│   │   │   ├── ProductDetailsPageOne.jsx
│   │   │   ├── AccountPage.jsx
│   │   │   ├── WishlistPage.jsx
│   │   │   ├── VendorPage.jsx
│   │   │   ├── BlogPage.jsx
│   │   │   └── ...
│   │   ├── App.js            # Root component with routing
│   │   └── index.js          # Entry point
│   └── package.json
├── documentation/            # Project documentation site
└── README.md

Hackathon Challenge Areas

Teams will implement backend subsystems using Valkey:

Subsystem	Description
User Authentication	Login, registration, session management
Catalog	Product catalog with DocumentDB
Shopping Cart	Cart management with coupon support
Trending Products	Track and display trending items
Ads	Advertisement placement and targeting
Full-Text Search	Product search with Valkey Search
Vector Similarity Search	Semantic product search
Analytics	Metrics with Prometheus
Observability	Logging and tracing with OpenSearch
Checkout	Order processing with inventory tracking
Delivery	Delivery tracking with geolocation
Rate Limiting	API rate limiting
Real-time Recommendations	Personalized product suggestions
Agentic Search	AI-powered search experience

Connecting to Valkey

Use the valkey-bundle Docker image to access all Valkey modules:

docker pull valkey/valkey-bundle:9-alpine
docker run -d --name valkey -p 6379:6379 valkey/valkey-bundle:9-alpine

Connect from your backend service:

Host: localhost
Port: 6379

Useful Commands

Command	Description
npm start	Start development server
npm test	Run tests in watch mode
CI=true npm test	Run tests once
CI=true npm test -- --coverage	Run tests with coverage
npm run build	Create production build
docker exec -it valkey valkey-cli	Open Valkey CLI

License

This project is open source and available for educational and hackathon purposes.