A modern, full-stack e-commerce application built with Next.js, React, MongoDB, and Tailwind CSS. This project demonstrates a complete shopping experience with product browsing, cart management, and checkout functionality.
- Features
- Tech Stack
- Project Structure
- Prerequisites
- Setup Instructions
- Running the Application
- Database Models
- API Endpoints
- Component Overview
- Usage Guide
- Troubleshooting
- Future Enhancements
✅ Product Catalog - Browse a responsive grid of products with descriptions and prices ✅ Shopping Cart - Add, remove, and adjust quantities of items ✅ Cart Persistence - Cart state managed in client-side memory ✅ Checkout System - Collect customer information and process orders ✅ Order Receipts - Display confirmation with order ID after successful checkout ✅ MongoDB Integration - Persistent storage for products and orders ✅ Responsive Design - Mobile, tablet, and desktop optimized layouts ✅ Type Safety - Full TypeScript support throughout the application ✅ Accessible Components - ShadCN UI components with built-in accessibility ✅ Real-time Updates - Instant cart total calculations and UI updates
- Next.js 15 - React-based full-stack framework with App Router
- React 19 - UI library for interactive components
- TypeScript - Static type checking and better developer experience
- Tailwind CSS v4 - Utility-first CSS framework for styling
- ShadCN/UI - Pre-built, accessible UI components (Button, Card, Modal, etc.)
- Lucide React - Icon library for UI elements
- Next.js API Routes - Built-in serverless API endpoints
- Node.js Runtime - JavaScript runtime for server-side logic
- MongoDB - NoSQL database for flexible data storage
- Mongoose - ODM (Object Document Mapper) for schema definition and validation
- Vercel - Recommended deployment platform
- GitHub - Version control and deployment integration
``` e-commerce-cart-app/ ├── app/ │ ├── page.tsx # Main page with cart state management │ ├── layout.tsx # Root layout with metadata │ ├── globals.css # Global styles and design tokens │ └── api/ │ ├── products/ │ │ └── route.ts # GET /api/products endpoint │ ├── checkout/ │ │ └── route.ts # POST /api/checkout endpoint │ └── cart/ │ └── [id]/ │ └── route.ts # Cart item operations (future use) ├── components/ │ ├── header.tsx # Navigation bar with cart icon │ ├── products-grid.tsx # Responsive product display grid │ ├── cart-sidebar.tsx # Slide-out shopping cart panel │ └── checkout-modal.tsx # Checkout form and receipt modal ├── models/ │ ├── Product.ts # Product schema with validation │ └── Order.ts # Order schema with timestamps ├── lib/ │ └── mongodb.ts # MongoDB connection with singleton pattern ├── scripts/ │ └── seed-products.ts # Script to populate sample products └── README.md # This file ```
Before running this application, ensure you have:
- Node.js 18.0.0 or higher
- npm or yarn package manager
- MongoDB Account (local or cloud-based)
The application requires a MongoDB connection string. Add it as an environment variable:
Connection String Examples:
-
MongoDB Atlas (Cloud): ``` mongodb+srv://username:password@cluster-name.mongodb.net/dbname?retryWrites=true&w=majority ```
-
Local MongoDB: ``` mongodb://localhost:27017/ecommerce ```
- Click the Publish button in the top right corner
- Follow the prompts to authenticate with GitHub
- Select repository settings
- Vercel will automatically configure environment variables
- Your app will be live in seconds!
-
Click the GitHub icon in the top right
-
Push code to your GitHub repository
-
Clone locally: ```bash git clone https URL cd ecommerce-cart-app ```
-
Install dependencies: ```bash npm install ```
-
Create
.env.localfile in the root: ``` MONGODB_URI=your_mongodb_connection_string ``` -
Run development server: ```bash npm run dev ```
-
Open http://localhost:3000 in your browser
- Click the three dots (...) in the top right
- Select "Download ZIP"
- Extract the archive
- Follow the GitHub setup steps 4-7 above
```bash npm run dev ``` Server runs on http://localhost:3000 with hot reload enabled.
```bash npm run build npm start ```
The application includes 8 sample products (headphones, cables, cases, etc.).
- Go to the
/scriptsfolder - Click the Execute button on
seed-products.ts - Check your MongoDB to see the products created
Locally: ```bash npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/seed-products.ts ```
Stores all available products for sale.
```typescript { _id: ObjectId, name: String (required), price: Number (required), description: String (optional), stock: Number (default: 100), createdAt: Date, updatedAt: Date } ```
Example: ```json { "_id": "507f1f77bcf86cd799439011", "name": "Wireless Headphones", "price": 79.99, "description": "Premium noise-cancelling headphones with 30-hour battery", "stock": 50, "createdAt": "2024-01-15T10:30:00Z" } ```
Stores all customer orders and transactions.
```typescript { _id: ObjectId, name: String (required), email: String (required), items: [ { productId: String, name: String, price: Number, quantity: Number } ], total: Number (required), createdAt: Date, updatedAt: Date } ```
Example: ```json { "_id": "507f1f77bcf86cd799439012", "name": "John Doe", "email": "john@example.com", "items": [ { "productId": "507f1f77bcf86cd799439011", "name": "Wireless Headphones", "price": 79.99, "quantity": 1 } ], "total": 79.99, "createdAt": "2024-01-15T11:45:00Z" } ```
Retrieves all available products from the database.
Request: ```bash GET /api/products ```
Response (200 OK): ```json [ { "_id": "507f1f77bcf86cd799439011", "name": "Wireless Headphones", "price": 79.99, "description": "Premium noise-cancelling headphones", "stock": 50, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } ] ```
Error Response (500 Internal Server Error): ```json { "error": "Failed to fetch products" } ```
Processes a checkout request and creates an order in the database.
Request Body: ```json { "cartItems": [ { "productId": "507f1f77bcf86cd799439011", "name": "Wireless Headphones", "price": 79.99, "quantity": 1 } ], "name": "John Doe", "email": "john@example.com" } ```
Response (200 OK): ```json { "orderId": "507f1f77bcf86cd799439012", "name": "John Doe", "email": "john@example.com", "items": [ { "name": "Wireless Headphones", "price": 79.99, "quantity": 1 } ], "total": 79.99, "message": "Order placed successfully!" } ```
Error Response (400 Bad Request): ```json { "error": "Missing required fields: cartItems, name, email" } ```
Displays the application logo and shopping cart icon with item count badge.
Props:
cartCount: number- Number of items in cartonCartClick: () => void- Callback when cart icon is clicked
Features:
- Responsive navigation bar
- Cart count badge
- Click to open/close cart
Displays all products in a responsive grid layout.
Features:
- Fetches products from
/api/productson mount - Responsive grid: 1 column (mobile) → 2 columns (tablet) → 4 columns (desktop)
- Loading spinner while fetching
- Add to cart button for each product
- Product details: name, description, price
Slide-out panel showing current cart items and checkout option.
Features:
- Slide-in animation from the right
- Display all items with quantity controls
- Increase/decrease quantity buttons
- Remove item button
- Cart total calculation
- Checkout button
- Empty cart state message
Modal form for collecting customer information and displaying order receipt.
States:
- Form State - Collect name and email
- Receipt State - Show order confirmation with details
Features:
- Input validation for name and email
- Displays cart summary
- Shows calculated total
- Generate order ID on successful checkout
- Confirmation message with order details
- The homepage displays all available products in a grid
- Scroll through products and view descriptions and prices
- Products load automatically when the page loads
- Click the "Add to Cart" button on any product
- Select desired quantity
- Item is added to cart (cart counter updates in header)
- Click the cart icon in the header
- Cart sidebar slides in from the right
- Shows all items with individual prices and quantities
- Increase Quantity: Click the + button next to an item
- Decrease Quantity: Click the − button next to an item
- Remove Item: Click the trash icon next to an item
- Cart Total: Updates automatically as you modify items
- Click the "Proceed to Checkout" button in the cart sidebar
- Enter your full name
- Enter your email address
- Review order summary and total
- Click "Complete Order" button
- After successful checkout, you'll see an order receipt modal
- Receipt displays:
- Order ID
- Your name and email
- Itemized list of products with quantities
- Order total
- Close the modal to return to shopping
Potential features for expanding the application:
- User Authentication - Login/signup with Supabase or NextAuth
- Product Filtering & Search - Search by name, filter by price range
- Product Reviews - Customer ratings and comments
- Wishlist Feature - Save favorite items
- Payment Integration - Stripe or PayPal integration
- Order History - Track customer orders
- Admin Dashboard - Manage products and orders
- Product Images - Display product photos in grid
- Stock Management - Update inventory after checkout
- Email Notifications - Send order confirmation emails
- Multi-currency Support - Display prices in different currencies
Contributions are welcome! To contribute:
- Fork the repository on GitHub
- Create a feature branch (
git checkout -b feature/YourFeature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/YourFeature) - Open a Pull Request
This project is open source and available under the MIT License.
- Next.js Documentation: https://nextjs.org/docs
- MongoDB Documentation: https://docs.mongodb.com
- Tailwind CSS: https://tailwindcss.com/docs
- ShadCN/UI Components: https://ui.shadcn.com
- Mongoose Documentation: https://mongoosejs.com
Created with Next.js, React, MongoDB, and Tailwind CSS
Happy shopping! 🛒