Previewer - Self-Hosted PR Preview Deployments

A self-hosted GitHub App that automatically builds and deploys preview environments for Pull Requests, similar to Vercel previews but for your own infrastructure.

Features

• Automatic PR Previews: Builds and deploys a preview for every PR opened or updated
• GitHub App Integration: Comments on PRs with preview status and URLs
• Dashboard: Web interface to manage repositories, view builds, and check logs
• Build Queue: Configurable concurrency for parallel builds
• Environment Variables: Encrypted storage for per-repository env vars
• Node Version Management: Supports Node.js 22 and 24 via n
• pnpm Support: Respects packageManager field in package.json
• Reverse Proxy: Routes /{repo-id}-pr-{pr-number}/* to preview servers
• Auto-Recovery: Restores preview servers after service restart
• Vibe Coded: Claude wrote this, if it's broken blame him

Why?

Vercel previews are great but not free for teams, and sometimes you want full control over your preview infrastructure. This runs on your own servers/Kubernetes cluster and integrates with your existing CI/CD pipeline.

Tech Stack

• Backend: Hono (TypeScript) - lightweight, fast, and modern
• Frontend: React + shadcn/ui + Tailwind CSS
• Database: PostgreSQL with Drizzle ORM
• Build System: Vite for the dashboard, tsc for the backend

Built primarily with Claude Opus 4.5, which means it mostly works but don't be surprised if something weird happens.

Setup

Prerequisites

• Node.js 24+
• PostgreSQL database
• pnpm package manager
• A GitHub App configured for your organization

GitHub App Configuration

Create a GitHub App with the following permissions:

• Repository permissions:
  • Contents: Read
  • Pull requests: Read & Write
  • Metadata: Read
• Subscribe to events:
  • Pull request

For the Webhook URL you can generate a public reachable endpoint to your local environment with cloudflared.

cloudflared tunnel --url http://localhost:3000

Installation

1. Clone the repository and install dependencies:

pnpm install

2. Copy .env.example to .env and fill in the values

3. Push database schema:

pnpm db:push

4. Start the development server:

pnpm dev

The application will be available at http://localhost:3000.

Production

Build and run for production:

pnpm build
pnpm start

Or use Docker:

docker build -t previewer .
docker run -p 3000:3000 --env-file .env previewer

Usage

1. Add a Repository: Go to the dashboard and add repositories from your GitHub App installation
2. Open a PR: The service will automatically build and deploy a preview
3. Check the PR: A comment will be posted with the preview URL
4. View Logs: Use the dashboard to view build logs and troubleshoot failures

Next.js Configuration

Your Next.js app must have output: 'standalone' in next.config.js:

const nextConfig = {
  output: 'standalone',
};

The previewer automatically injects basePath for proper routing under the preview URL.

Architecture

                                    +------------------+
                                    |   GitHub App     |
                                    +--------+---------+
                                             |
                                    Webhook (PR events)
                                             |
                                             v
+------------------+              +----------+---------+
|    Dashboard     | <---HTTP---> |   Previewer API    |
|   (React SPA)    |              |      (Hono)        |
+------------------+              +----------+---------+
                                             |
                      +----------------------+----------------------+
                      |                      |                      |
                      v                      v                      v
             +--------+-------+    +---------+--------+    +--------+-------+
             |  Build Queue   |    | Preview Manager  |    |   PostgreSQL   |
             | (Clone, Build) |    | (Node processes) |    |   (Drizzle)    |
             +----------------+    +------------------+    +----------------+

License

MIT