genesis

2025-09-02 08:29:27 +00:00
commit 9cfbe4c0f7
10 changed files with 6981 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,150 @@
+# Webpack HMR React Counter App
+
+A React application built with Webpack that features Hot Module Replacement (HMR), WebSocket-based real-time counter syncing, and REST API endpoints. Multiple users can increment a shared counter that syncs across all connected clients.
+
+## Features
+
+- **React 18** with modern hooks
+- **Webpack 5** with Hot Module Replacement (HMR)
+- **WebSocket** real-time communication for counter syncing
+- **Express API** server with REST endpoints
+- **Nginx proxy** configuration for production deployment
+
+## Architecture
+
+- **Frontend**: React app served on `127.0.0.1:3000` with Webpack Dev Server
+- **Backend API**: Express server on `127.0.0.1:3001` handling REST API and WebSocket
+- **WebSocket**: Real-time counter updates broadcast to all connected clients
+- **Proxy**: Webpack dev server proxies `/api` requests to the Express server
+- **External Access**: Configured for access via `https://dummy7.ddns.net` with dynamic WebSocket URLs
+
+## API Endpoints
+
+- `GET /api/counter` - Get current counter value
+- `POST /api/counter/increment` - Increment counter and broadcast update
+
+## WebSocket Events
+
+- **Connection URL**: `ws://localhost:3001/counter-ws` (local) or `wss://dummy7.ddns.net/counter-ws` (external)
+- `counter-update` - Broadcast when counter changes with new value
+
+## Local Development
+
+### Prerequisites
+
+- Node.js (v14 or higher)
+- npm
+
+### Installation
+
+1. Clone or download the project files
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+### Running the Application
+
+Start both the React dev server and Express API server concurrently:
+```bash
+npm start
+```
+
+This will:
+- Start the Express server on `http://127.0.0.1:3001` (internal only)
+- Start the Webpack dev server with HMR on `http://127.0.0.1:3000` (internal only)
+- Open the app in your default browser
+
+### External Access via Nginx Proxy
+
+The servers listen only on `127.0.0.1` for security. External access is handled through Nginx proxy:
+
+- **Local development**: `http://localhost:3000` or `http://127.0.0.1:3000`
+- **External access**: `https://dummy7.ddns.net` (proxied through Nginx)
+
+The WebSocket connections automatically use the correct protocol based on the current domain:
+- When accessed via `https://dummy7.ddns.net` → connects to `wss://dummy7.ddns.net`
+- Nginx proxies WebSocket connections to the internal `ws://127.0.0.1:3001`
+
+### Manual Commands
+
+Run servers separately if needed:
+```bash
+# Start only the API/WebSocket server
+npm run server
+
+# Start only the React dev server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## Testing Real-time Syncing
+
+1. Open `http://127.0.0.1:3000` in multiple browser tabs/windows
+2. Click the "Increment" button in any tab
+3. Observe the counter update in real-time across all tabs
+
+## Production Deployment
+
+### Using Nginx Proxy
+
+Use the provided `nginx.conf` snippet to proxy requests:
+
+1. Copy the server block from `nginx.conf` to your Nginx configuration
+2. Update `server_name` to your domain (e.g., `dummy7.ddns.net`)
+3. For HTTPS, uncomment and configure SSL certificate paths
+4. Adjust VSCode server port if different (default: 8080)
+5. Reload Nginx: `sudo nginx -s reload`
+
+### External Access
+
+The app will be accessible at `https://dummy7.ddns.net` (configure SSL as needed).
+
+### Important Notes
+
+- The counter is stored in memory and resets on server restart
+- WebSocket connections are handled on the Express server (port 3001)
+- The React app connects to WebSocket at `ws://127.0.0.1:3001`
+
+## Project Structure
+
+```
+├── src/
+│   ├── index.js          # React app entry point
+│   └── App.js            # Main counter component
+├── public/
+│   └── index.html        # HTML template
+├── server.js             # Express API/WebSocket server
+├── webpack.config.js     # Webpack configuration with HMR
+├── package.json          # Dependencies and scripts
+├── nginx.conf            # Nginx proxy configuration
+└── README.md             # This file
+```
+
+## Technologies Used
+
+- **Frontend**: React 18, Webpack 5, Babel
+- **Backend**: Express.js, WebSocket (ws library)
+- **Development**: Webpack Dev Server, Hot Module Replacement
+- **Deployment**: Nginx proxy
+
+## Troubleshooting
+
+- **Port conflicts**: Ensure ports 3000 and 3001 are available
+- **WebSocket connection issues**: Check that the Express server is running on port 3001
+- **HMR not working**: Verify Webpack dev server is running and browser console for errors
+- **API calls failing**: Confirm the proxy configuration in `webpack.config.js`
+- **"Invalid host header" error**: Added `allowedHosts: 'all'` and `client.webSocketURL: 'auto://0.0.0.0:0/ws'` in webpack config to allow proxy access and automatic HMR WebSocket URL detection
+- **WebSocket connection failures when accessing externally**: WebSocket URL is now dynamic based on current host (supports both HTTP/WS and HTTPS/WSS)
+- **External domain access**: Use the provided Nginx configuration to proxy requests properly - servers listen on 127.0.0.1 only
+- **Nginx WebSocket proxy**: Ensure Nginx is configured with proper WebSocket upgrade headers for `/ws` location
+
+## Future Enhancements
+
+- Add user authentication
+- Implement persistent storage (database)
+- Add multiple counters/rooms
+- Include user presence indicators
+- Add counter reset functionality