Matrix GIF Widget

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.

Features

• Trending GIFs: Browse currently trending GIFs.
• 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.

Tech Stack

• Frontend: React, Vite, TypeScript
• Backend: Node.js, Express
• Styling: CSS Modules / Standard CSS
• API: Giphy API

Prerequisites

• Node.js (v20 or later)
• npm or yarn
• Docker (optional, for containerized deployment)
• Giphy API Key (Get one from developers.giphy.com)

Installation & Setup

1. Clone the repository

git clone <repository-url>
cd gif

2. Environment Configuration

Create a .env file in the root directory based on .env.example:

cp .env.example .env

Edit .env and add your Giphy API Key:

GIPHY_API_KEY=your_actual_giphy_api_key
PORT=3000 # Optional, defaults to 3000

3. Local Development

Install dependencies:

npm install

Start the development server (Frontend only, usually on port 5173):

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):

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:

docker compose up -d --build

The widget will be accessible at http://localhost:3000.

Manual Docker Build

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.