Game Cave 🎮

🎯 Featured Games

🧱 Classic Arcade	🧩 Strategy & Logic	🎲 Casual Fun
🧱 Brick Breaker	🔴 Connect Four	🎯 Number Guesser
🐍 Snake	🎯 Tic Tac Toe	🪨 Rock Paper Scissors
🏓 Pong	💣 Minesweeper	🔤 Word Scramble
	🧠 Memory Match	⚡ Typing Test
	🎪 Hangman

🌟 Game Highlights

🧱 Brick Breaker - Classic arcade action with paddle and ball physics
🐍 Snake - Navigate the snake to collect food and grow longer
🔴 Connect Four - Strategic gameplay to connect four pieces in a row
💣 Minesweeper - Clear the minefield using logic and deduction
🧠 Memory Match - Test your memory with card matching gameplay
🏓 Pong - The original tennis-style arcade game
🎯 Tic Tac Toe - Classic 3x3 grid strategy game
🎪 Hangman - Guess the word before the drawing is complete
🎯 Number Guesser - Challenge your intuition with number guessing
🪨 Rock Paper Scissors - The timeless hand game
⚡ Typing Test - Improve your typing speed and accuracy
🔤 Word Scramble - Unscramble letters to form words

🤖 AI-Enhanced Features

Experience the power of Google Gemini AI integrated into select games:

🎪 Hangman - AI generates dynamic word hints and contextual clues
🔤 Word Scramble - Smart difficulty adjustment and AI-powered word generation
🎯 Tic Tac Toe - AI opponent with adaptive difficulty levels
🧠 Memory Match - Intelligent pattern analysis and performance insights
⚡ Typing Test - AI-curated text content and personalized improvement suggestions

💡 Pro Tip: Set up your Gemini API key to unlock these enhanced AI features! The games work perfectly without it, but AI features add an extra layer of intelligence and personalization.

✨ Key Features

🎮 12 Classic Games - A diverse collection of timeless games
🤖 AI-Powered Features - Enhanced gameplay with Google Gemini AI integration
📱 Responsive Design - Perfect on desktop, tablet, and mobile
⚡ Lightning Fast - Built with Vite for optimal performance
🎨 Modern UI - Clean, intuitive interface with TailwindCSS
🔧 Type Safe - Written in TypeScript for reliability
🔄 Server-Side Rendering (SSR) - Faster initial page loads and better SEO
🐳 Docker Ready - Containerized deployment for any environment
🌐 Nginx-Optimized Builds - Production images served behind Nginx
🌐 Multi-Platform Deploy - Vercel, Docker, or cloud platforms
🎯 PWA Ready - Can be installed as a Progressive Web App
🔄 State Management - Smooth game state handling
🎵 Sound Effects - Immersive audio feedback (coming soon)
🏆 Score Tracking - Keep track of your best performances

🚀 Quick Start

Choose your preferred setup method:

🏃‍♂️ Local Development (Recommended for development)

Standard npm setup with hot reload
Perfect for development and customization

🐳 Docker Deployment (Recommended for consistency)

Containerized environment
Works identically across all platforms
Great for teams and production

🌐 Cloud Deployment (Recommended for production)

One-click deploy to Vercel
Instant global CDN distribution

📦 Installation

Clone the repository:

git clone https://github.com/kevinThulnith/multi-stage-react-project.git

Navigate to the project directory:
```
cd multi-stage-react-project
```
Install dependencies:
```
npm i
```
Set up environment variables (required for AI features):

Create a .env file in the root directory:
```
# In the root directory
touch .env
```
Add the following environment variables to your .env file:
```
# Required: Gemini API Key for AI-powered game features
VITE_GEMINI_API_KEY=your_gemini_api_key_here
```
Note: The VITE_GEMINI_API_KEY is now actively used in some games for AI-powered features. You can obtain a free API key from Google AI Studio. While the games will still function without the API key, some AI-enhanced features will be disabled.

🎮 Running the Games

Development Mode

npm run dev

// On local Network
npx vite --host {Device Ip Address}

Starts the development server at http://localhost:5173/_

Production Build

npm run build

Creates an optimized production build with SSR support_

Server-Side Rendering (SSR) Mode

npm run serve

Runs the production build with SSR for better SEO and faster initial loads_

Preview Build

npm run preview

Preview the production build locally_

Network Access - Run on your local network for testing on multiple devices_

npm run host

🌐 Deployment

Deploy to Vercel

The easiest way to deploy your Game Cave is using Vercel:

One-Click Deploy:

Manual Deployment:

# Install Vercel CLI
npm i -g vercel

# Deploy from the root directory
cd multi-stage-react-project
vercel

GitHub Integration:
- Connect your repository to Vercel
- Automatic deployments on every push to main branch
- Preview deployments for pull requests

Build Configuration

For Vercel deployment, make sure your build settings are:

Build Command: npm run build
Output Directory: dist
Install Command: npm install
Root Directory: multi-stage-react-project

Environment Variables

For enhanced AI-powered gameplay features, you'll need to set up the Gemini API key. While basic gameplay works without it, some games include AI-enhanced features that require this configuration.

Create a .env file in the root directory:

touch .env  # On Windows: type nul > .env

Add the following variables:

# Required for AI-powered game features
VITE_GEMINI_API_KEY=your_gemini_api_key_here

Get your Gemini API Key:
- Visit Google AI Studio
- Create a new API key
- Replace your_gemini_api_key_here with your actual key
For Vercel deployment:
- Go to your Vercel project dashboard
- Navigate to Settings > Environment Variables
- Add VITE_GEMINI_API_KEY with your API key value

Important: Never commit your .env file to version control. The .env file is already included in .gitignore for your security.

🐳 Docker Deployment

Containerize Game Cave with Docker for consistent deployment across any environment! Perfect for development, testing, and production deployments.

📋 Prerequisites

Ensure Docker is installed on your system:

# Check if Docker is installed
docker --version

# Check if Docker Compose is available
docker compose version

Need Docker? Download from docker.com - Available for Windows, macOS, and Linux

🚀 Quick Start with Docker

Method 1: Direct Docker Build & Run

Navigate to the project directory:
```
cd multi-stage-react-project
```
Build the Docker image:
```
# Basic build (without AI features)
docker build -t game-cave:dev .

# Build with Gemini API key for AI-powered features
docker build --build-arg VITE_GEMINI_API_KEY=your_gemini_api_key_here -t game-cave:dev .
```
Note: Using --build-arg VITE_GEMINI_API_KEY passes the API key as a build argument to enable AI-powered features in games like Hangman, Word Scramble, and Tic Tac Toe. Replace your_gemini_api_key_here with your actual Gemini API key from Google AI Studio.
Verify the image was created:
```
docker images | grep game-cave
```

Run the container:

# Run created docker image
docker run -p 5173:5173 game-cave:dev

# Run created docker image as background process
docker run -d -p 5173:5173 game-cave:dev

# Run created docker image with custome container name
docker run -p 5173:5173 --name game-cave-dev game-cave:dev

Access your games:
- 🌐 Local: http://localhost:5173
- 📱 Network: http://your-ip-address:5173

Method 2: Docker Compose (Recommended)

# Navigate to project directory
cd multi-stage-react-project

# Start the application with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

# Stop the application
docker compose down

On the `docker` branch, Compose exposes Nginx on port 5173 by default for a static SPA build. On the `docker+ssr` branch, Compose starts both the SSR Node app and Nginx, with Nginx reverse‑proxying traffic to the app (typically on port 3000) and serving static assets directly for optimal performance.

🛠️ Docker Commands Cheat Sheet

Command	Description
`docker build -t game-cave:dev .`	Build development image
`docker build --build-arg VITE_GEMINI_API_KEY=your_key -t game-cave:dev .`	Build with AI features
`docker run -p 5173:5173 game-cave:dev`	Run dev container
`docker run -p 5173:5173 game-cave:prod`	Run prod (Nginx static)
`docker run -p 5173:5173 game-cave:ssr`	Run prod (Nginx + SSR)
`docker ps`	List running containers
`docker stop game-cave-dev`	Stop container
`docker rm game-cave-dev`	Remove container
`docker rmi game-cave:dev`	Remove image
`docker logs game-cave-dev`	View container logs

🔧 Advanced Configuration

Environment Variables

# Run with custom environment variables
docker run -p 5173:5173 \
  -e NODE_ENV=development \
  -e VITE_API_URL=http://localhost:3000 \
  --name game-cave-dev \
  game-cave:dev

Volume Mounting for Development

# Mount source code for hot reload during development
docker run -p 5173:5173 \
  -v "$(pwd):/app" \
  -v /app/node_modules \
  --name game-cave-dev \
  game-cave:dev

Multi-Stage Production Build

# Example production Dockerfile (Dockerfile.prod)
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine AS production
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

For SSR, Nginx acts as a reverse proxy to the Node server and may also serve static assets directly. Example (simplified):

# Example nginx.conf (docker+ssr branch)
worker_processes auto;
events { worker_connections 1024; }
http {
   include       /etc/nginx/mime.types;
   sendfile      on;
   gzip          on;
   gzip_types    text/plain application/javascript text/css application/json image/svg+xml;

   upstream app {
      server 127.0.0.1:3000; # Node SSR server
   }

   server {
      listen 80;
      server_name _;

      # Serve built assets directly if desired
      location /assets/ {
         root /usr/share/nginx/html;
         access_log off;
         expires 1y;
         add_header Cache-Control "public, max-age=31536000, immutable";
      }

      # Proxy everything else to SSR
      location / {
         proxy_pass         http://app;
         proxy_http_version 1.1;
         proxy_set_header   Upgrade $http_upgrade;
         proxy_set_header   Connection "upgrade";
         proxy_set_header   Host $host;
         proxy_set_header   X-Forwarded-Proto $scheme;
         proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
      }
   }
}

🌐 Network Access & Mobile Testing

# Run on all interfaces for network access
docker run -p 0.0.0.0:5173:5173 --name game-cave-dev game-cave:dev

# Find your IP address

# Windows PowerShell:
ipconfig | findstr IPv4

# macOS/Linux:
ifconfig | grep inet

Now you can test on mobile devices using http://your-ip:5173

For Nginx-based production images (docker or docker+ssr branches), map port 5173 and test via http://your-ip/.

🐛 Troubleshooting

Common Issues & Solutions

Issue	Solution
Port already in use	Use different port: `-p 3000:5173`
Permission denied	Run with `sudo` (Linux/macOS) or check Docker Desktop (Windows)
Image not found	Rebuild image: `docker build -t game-cave:dev .`
Container won't start	Check logs: `docker logs game-cave-dev`

Clean Slate Reset

# Stop and remove all Game Cave containers
docker stop $(docker ps -q --filter ancestor=game-cave:dev)
docker rm $(docker ps -aq --filter ancestor=game-cave:dev)

# Remove all Game Cave images
docker rmi $(docker images game-cave -q)

# Clean up unused Docker resources
docker system prune -af

🚢 Production Deployment

Docker Hub Deployment

# Tag your image
docker tag game-cave:dev yourusername/game-cave:latest

# Push to Docker Hub
docker push yourusername/game-cave:latest

# Deploy anywhere
docker run -p 80:80 yourusername/game-cave:latest

Cloud Deployment Options

🌊 DigitalOcean App Platform - One-click Docker deployment
☁️ AWS ECS/Fargate - Scalable container orchestration
🔵 Azure Container Instances - Serverless containers
🌐 Google Cloud Run - Pay-per-use container platform

📊 Container Health & Monitoring

# Monitor container resources
docker stats game-cave-dev

# Health check
docker exec game-cave-dev curl -f http://localhost:5173 || exit 1

# Container shell access
docker exec -it game-cave-dev sh

🎯 Why Docker for Game Cave?

✅ Consistent Environment - Same setup across all machines
✅ Quick Setup - Get running in minutes, not hours
✅ Isolated Dependencies - No conflicts with system packages
✅ Easy Cleanup - Remove everything with one command
✅ Production Ready - Scale from dev to production seamlessly
✅ Team Collaboration - Everyone runs the same environment

🛠️ Tech Stack

Frontend Technologies

⚛️ React 19 - Modern UI library with hooks and functional components
📘 TypeScript - Type-safe JavaScript for better development experience
⚡ Vite - Lightning-fast build tool and development server with SSR support
🎨 TailwindCSS - Utility-first CSS framework for rapid UI development
🔧 ESLint - Code linting for maintaining code quality
🔄 Express.js - Server-side rendering and API handling

AI & Intelligence

🤖 Google Gemini AI - Advanced AI integration for enhanced gameplay features
🧠 Smart Game Logic - AI-powered hints, difficulty adjustment, and content generation
📊 Intelligent Analytics - AI-driven performance insights and personalized recommendations

Deployment & DevOps

🐳 Docker - Containerization for consistent deployments
🌐 Vercel - Serverless deployment platform
☁️ Multi-Cloud Ready - AWS, Azure, Google Cloud, DigitalOcean

🌳 Development Branches

This repository contains multiple branches representing different development stages and feature implementations:

📋 Branch Overview

Branch	Description	Status	Features
🌟 `main`	Production-ready version	✅ Active	Full game collection with modern React setup
🐳 `docker`	Docker containerization	✅ Active	Docker + Nginx static serving for production
🔄 `SSR-Server-Side-Rendering`	Server-side rendering implementation	✅ Active	Enhanced SEO and faster initial loads
🚀 `docker+ssr`	Combined SSR and Docker	✅ Active	Nginx reverse proxy + Node SSR, optimized static asset handling

🔄 Branch Development Flow

graph LR
   A[main] --> B[docker]
   A --> C[SSR-Server-Side-Rendering]
   B --> D[docker+ssr]
   C --> D

🎯 Choosing the Right Branch

For basic development: Use main branch
For containerized deployment: Check out docker branch
For SEO optimization: Use SSR-Server-Side-Rendering branch
For production deployment: Use docker+ssr branch (recommended)

🔀 Switching Branches

# View all branches
git branch -a

# Switch to a specific branch
git checkout docker
git checkout SSR-Server-Side-Rendering
git checkout docker+ssr

# Return to main branch
git checkout main

🚀 Branch-Specific Features

🐳 Docker Branch (with Nginx)

Complete Docker containerization
Multi-stage build process
Development and production Dockerfiles
Docker Compose configuration
Nginx serves optimized static build on port 80 with sensible cache headers

🔄 SSR Branch

Server-side rendering with Express.js
Enhanced SEO capabilities
Faster initial page loads
Better Core Web Vitals scores

🚀 docker+ssr Branch (Nginx + SSR)

Combined benefits of SSR and Docker
Production-ready deployment
Scalable architecture
Cloud deployment optimized
Nginx reverse proxies to Node SSR and serves static assets directly when possible

Note: The Nginx configuration and Dockerfiles referenced above live in the respective branches (docker and docker+ssr). This main branch README documents how to use them.

🤝 Contributing

We welcome contributions! Here's how you can help:

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-game)
💝 Commit your changes (git commit -m 'Add some amazing game')
📤 Push to the branch (git push origin feature/amazing-game)
🎉 Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

🎮 Inspired by classic arcade and casual games
⚡ Built with modern web technologies for the best user experience
🤖 Enhanced with Google Gemini AI for intelligent gameplay features
🌐 Deployed on Vercel for blazing-fast global delivery
🙏 Thanks to all contributors who help make this project better!
💡 Special thanks to the React, TypeScript, Vite, and Google AI communities

📊 Project Stats

🎯 12 Games implemented and ready to play
🤖 AI-Enhanced - 5 games feature Google Gemini AI integration
📦 Lightweight Bundle - Optimized for fast loading
🌍 Global CDN - Fast delivery worldwide via Vercel
📱 Mobile Optimized - Works perfectly on all devices
⚡ < 3s Load Time - Lightning-fast performance
🐳 Docker Ready - Container support for all environments
☁️ Multi-Cloud - Deploy anywhere with Docker containers

⭐ Don't forget to star this repository if you enjoyed the games! ⭐

Made with ❤️ by Kevin Thulnith

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.vscode		.vscode
public		public
src		src
.gitignore		.gitignore
README.md		README.md
eslint.config.js		eslint.config.js
face.png		face.png
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

kevinThulnith/multi-stage-react-project

Folders and files

Latest commit

History

Repository files navigation

Game Cave 🎮

🎯 Featured Games

🌟 Game Highlights

🤖 AI-Enhanced Features

✨ Key Features

🚀 Quick Start

🏃‍♂️ Local Development (Recommended for development)

🐳 Docker Deployment (Recommended for consistency)

🌐 Cloud Deployment (Recommended for production)

📦 Installation

🎮 Running the Games

Development Mode

Production Build

Server-Side Rendering (SSR) Mode

Preview Build

Network Access - Run on your local network for testing on multiple devices_

🌐 Deployment

Deploy to Vercel

Build Configuration

Environment Variables

🐳 Docker Deployment

📋 Prerequisites

🚀 Quick Start with Docker

Method 1: Direct Docker Build & Run

Method 2: Docker Compose (Recommended)

🛠️ Docker Commands Cheat Sheet

🔧 Advanced Configuration

Environment Variables

Volume Mounting for Development

Multi-Stage Production Build

🌐 Network Access & Mobile Testing

🐛 Troubleshooting

Common Issues & Solutions

Clean Slate Reset

🚢 Production Deployment

Docker Hub Deployment

Cloud Deployment Options

📊 Container Health & Monitoring

🎯 Why Docker for Game Cave?

🛠️ Tech Stack

Frontend Technologies

AI & Intelligence

Deployment & DevOps

🌳 Development Branches

📋 Branch Overview

🔄 Branch Development Flow

🎯 Choosing the Right Branch

🔀 Switching Branches

🚀 Branch-Specific Features

🐳 Docker Branch (with Nginx)

🔄 SSR Branch

🚀 docker+ssr Branch (Nginx + SSR)

🤝 Contributing

📄 License

🙏 Acknowledgments

📊 Project Stats

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages