BugPin: Self-Hosted Visual Bug Reporting Tool

What is BugPin?

BugPin is a self-hosted, open-source visual bug reporting tool designed as a privacy-first alternative to SaaS solutions like Marker.io, BugHerd, and Usersnap. It allows teams and users to capture screenshots, annotate issues with built-in drawing tools, and submit bug reports directly from any web application — all without third-party dependencies. BugPin runs on your own server using Docker or Bun, stores all data locally in SQLite, and provides a lightweight embeddable widget (under 130KB) that works with any frontend framework.

Why BugPin?

• Self-Hosted: Your data stays on your servers. No third-party dependencies or data sharing.
• Visual Reporting: Capture screenshots with one click and annotate them with drawing tools.
• Lightweight Widget: Under 50KB gzipped, loads asynchronously, and uses Shadow DOM for style isolation.
• Offline Support: Reports are cached locally and automatically submitted when connectivity is restored.
• Easy Integration: Add to your site with a single script tag.

Key Features

Visual Bug Reporting

Capture full-page or visible area screenshots directly from your web application. The built-in annotation tools help provide clear context for every bug report.

Annotation Tools

• Pen tool for freehand drawing
• Rectangle and circle shapes
• Arrow for pointing to issues
• Text annotations
• Privacy blur for sensitive information

Self-Hosted & Private

BugPin is designed for self-hosting with a simple SQLite database and Docker deployment. All data is stored locally with no external dependencies.

Integrations

• Forward reports to GitHub Issues automatically
• Email notifications via SMTP configuration

Widget Features

Style Isolation

The BugPin widget uses Shadow DOM to encapsulate its styles, ensuring zero conflicts with your application:

• Widget styles won't affect your site's styles
• Your site's styles won't affect the widget
• Works seamlessly with any CSS framework (Tailwind, Bootstrap, Material UI, etc.)
• No global CSS pollution or naming collisions

Offline Support

The widget automatically handles offline scenarios with intelligent retry logic:

1. Local Caching: If the user is offline when submitting a report, it's cached locally using IndexedDB
2. Automatic Sync: When connectivity is restored, cached reports are automatically submitted in the background
3. Exponential Backoff: Failed submissions retry with exponential backoff (5 seconds → 10s → 20s → 40s → 80s, up to 5 minutes)
4. User Feedback: Users are notified when reports are saved offline and when they're successfully synced

This ensures no bug reports are lost due to network issues, making BugPin reliable even in unstable network conditions.

Framework Compatibility

BugPin works with any web framework or platform. The widget is a framework-agnostic JavaScript library that runs in the browser.

Frontend Frameworks

BugPin integrates seamlessly with all modern frontend frameworks:

• React / Next.js
• Vue.js / Nuxt
• Angular
• Svelte / SvelteKit
• Solid.js
• Qwik
• Vanilla JavaScript / HTML

Backend Frameworks

Since BugPin is a client-side widget, it works with any backend technology:

• .NET (ASP.NET Core, Blazor, Razor Pages)
• Node.js (Express, Fastify, NestJS)
• Python (Django, Flask, FastAPI)
• PHP (Laravel, Symfony, WordPress)
• Ruby (Rails, Sinatra)
• Go (Gin, Echo, Fiber)
• Java (Spring Boot, JSP)
• Static Sites (Hugo, Jekyll, 11ty)

Installation Methods

• Script Tag: Universal method, works everywhere
• npm Package: @arantic/bugpin-widget for module bundlers
• CDN: Load directly from your BugPin server

See the Widget Installation Guide for framework-specific examples.

Architecture

BugPin consists of three main components:

Component	Technology	Purpose
Server	Bun + Hono + SQLite	REST API, database, file storage
Admin Console	React 18 + Tailwind CSS	Dashboard for managing reports
Widget	Preact + Fabric.js	Embeddable bug reporter

Getting Started

Ready to get started? Follow the Docker installation guide to have BugPin running in under 5 minutes.