docs

README.md

@@ -1,73 +1,110 @@
-# React + TypeScript + Vite
+# Matrix GIF Widget
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+A React-based Matrix widget that allows users to search, browse, and send GIFs directly from their Matrix client (e.g., Element). This widget integrates with the Giphy API and includes a backend proxy to handle secure API requests and Matrix media uploads.
 
-Currently, two official plugins are available:
+## Features
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- **Trending GIFs:** Browse currently trending GIFs.
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- **Search:** Search for specific GIFs using keywords.
+- **Matrix Integration:** Seamlessly integrates as a widget in Matrix clients.
+- **Backend Proxy:** Securely handles Giphy API keys and CORS via a Node.js/Express backend.
+- **Media Upload:** Automatically uploads selected GIFs to the user's Matrix homeserver for persistent storage.
 
-## React Compiler
+## Tech Stack
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+- **Frontend:** React, Vite, TypeScript
+- **Backend:** Node.js, Express
+- **Styling:** CSS Modules / Standard CSS
+- **API:** Giphy API
 
-## Expanding the ESLint configuration
+## Prerequisites
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+- **Node.js** (v20 or later)
+- **npm** or **yarn**
+- **Docker** (optional, for containerized deployment)
+- **Giphy API Key** (Get one from [developers.giphy.com](https://developers.giphy.com/))
 
-```js
+## Installation & Setup
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
 
-      // Remove tseslint.configs.recommended and replace with this
+### 1. Clone the repository
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
 
-      // Other configs...
+```bash
-    ],
+git clone <repository-url>
-    languageOptions: {
+cd gif
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+### 2. Environment Configuration
 
-```js
+Create a `.env` file in the root directory based on `.env.example`:
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
 
-export default defineConfig([
+```bash
-  globalIgnores(['dist']),
+cp .env.example .env
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
 ```
+
+Edit `.env` and add your Giphy API Key:
+
+```env
+GIPHY_API_KEY=your_actual_giphy_api_key
+PORT=3000 # Optional, defaults to 3000
+```
+
+### 3. Local Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the development server (Frontend only, usually on port 5173):
+
+```bash
+npm run dev
+```
+
+**Note:** The standalone frontend dev server (`vite`) cannot proxy API requests to Giphy securely without the backend. For full functionality, you should build the project and run the server, or run the backend server alongside Vite if configured (current setup is designed for a unified build).
+
+To run the full stack locally (Build + Serve):
+
+```bash
+npm run build
+node server.js
+```
+
+The application will be available at `http://localhost:3000`.
+
+## Docker Deployment
+
+You can easily deploy this application using Docker.
+
+### Using Docker Compose (Recommended)
+
+1. Ensure your `.env` file is configured with your `GIPHY_API_KEY`.
+2. Run the application:
+
+```bash
+docker compose up -d --build
+```
+
+The widget will be accessible at `http://localhost:3000`.
+
+### Manual Docker Build
+
+```bash
+docker build -t matrix-gif-widget .
+docker run -p 3000:3000 --env-file .env matrix-gif-widget
+```
+
+## Adding to Matrix
+
+To add this as a custom widget in Element (or other clients):
+
+1. Host the application (so it's accessible via HTTPS).
+2. In Element, use the `/addwidget` command or the "Add Widget" UI.
+3. Enter the URL of your deployed application (e.g., `https://your-domain.com/`).
+
+## Project Structure
+
+- `/src` - React frontend source code.
+- `/server.js` - Express backend for API proxying and serving static files.
+- `Dockerfile` - Container definition for multi-stage build.

docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - GIPHY_API_KEY=${GIPHY_API_KEY}
+      - PORT=3000
+    restart: unless-stopped