ocelus/react-preview repository overview

⁠React Preview Server

A lightweight, standalone, and self-hosted tool to automatically deploy and serve preview environments for every branch of your React/Vite applications.

Fully powered by Node.js and Express, this project replaces complex infrastructures with a simple "plug & play" Docker container. It natively supports multiple repositories through a JSON configuration file.

⁠🚀 Features

• Multi-Project Support: Track and deploy multiple Git repositories simultaneously using a single projects.json configuration.
• Automatic Deployment: Monitors Git repositories and builds new branches or commits via polling.
• Built-in Web Server: Uses Express.js to serve static files efficiently.
• Native SPA Support: Automatic redirection to index.html for client-side routing (React Router, Vue Router).
• Dynamic Dashboard: Generates a home page listing all currently deployed branches per project.
• Persistent Cache: Speeds up build times by sharing the NPM dependency cache.

⁠🛠️ Prerequisites

• Docker installed on the host machine.
• Git repository(ies) configured to be built via npm run build and outputting a dist/ folder.

⁠⚙️ Configuration

You can configure the server using environment variables for a single project, or a projects.json file for multiple projects.

⁠Option 1: Single Project (Environment Variables)

docker run -d \
  -e REPO_URL="https://github.com/your-account/your-app.git" \
  -p 8080:80 \
  --name react-preview \
  react-preview-node

⁠Option 2: Multiple Projects (projects.json)

Create a projects.json file on your host machine to track multiple repositories.

[
  {
    "REPO_URL": "https://github.com/your-account/app-one.git",
    "GIT_TOKEN": "your_token",
    "BRANCH_REGEX": "^(master|feature)"
  },
  {
    "REPO_URL": "https://github.com/your-account/app-two.git"
  }
]

Run the container by mounting this file:

docker run -d \
  -v $(pwd)/projects.json:/projects.json \
  -p 8080:80 \
  --name react-preview \
  react-preview-node

⁠📝 URL Structure

The application automatically routes projects based on the repository name extracted from the REPO_URL:

http://your-domain.com/[PROJECT_NAME]/[BRANCH_NAME]/