Bug Buddy

A feedback widget system that captures screenshots, allows annotations, and automatically creates GitHub issues.

Prerequisites

• Node.js >= 24.12.0 < 25.0.0
• pnpm >= 9.0.0
• Docker and Docker Compose (for PostgreSQL)

Installation

1. Install dependencies:

   pnpm install

   Note: If you encounter Node version issues, use nvm to switch to the correct version:

   nvm use

2. Set up environment variables: Create a .env file in the root directory:

   # Database
   DATABASE_URL="postgresql://bugbuddy:bugbuddy@localhost:5432/bugbuddy?schema=public"
   KV_REST_API_URL="" (upstash redis url)
   KV_REST_API_TOKEN="" (upstash redis token)
   
   
   # Better Auth
   BETTER_AUTH_SECRET="your-secret-key-here-change-in-production"
   
   # OAuth (for user authentication)
   GITHUB_CLIENT_ID="your-github-client-id"
   GITHUB_CLIENT_SECRET="your-github-client-secret"
   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   
   # GitHub App (for creating issues as BugBuddy)
   GITHUB_APP_ID="123456"
   GITHUB_APP_SLUG="bug-buddy"
   GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n"
   GITHUB_APP_WEBHOOK_SECRET="your-webhook-secret"
   
   # PostHog (optional)
   NEXT_PUBLIC_POSTHOG_KEY=""
   NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"
   
   # Vercel Blob
   BLOB_READ_WRITE_TOKEN="your-blob-read-write-token"
   
   # Email
   EMAIL_HOST=
   EMAIL_PORT=
   EMAIL_USER=
   EMAIL_PASSWORD=

3. Start PostgreSQL database:

   docker-compose up -d

4. Set up Prisma:

   # Generate Prisma client
   pnpm db:generate
   
   # Push schema to database (for development)
   pnpm db:push
   
   # Or run migrations (for production)
   pnpm db:migrate

5. Start the development server:

   pnpm dev

OAuth Setup

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Go to "Credentials" > "Create Credentials" > "OAuth client ID"
5. Choose "Web application"
6. Add authorized redirect URIs:
   • Development: http://localhost:3000/api/auth/callback/google
   • Production: https://yourdomain.com/api/auth/callback/google
7. Copy the Client ID and Client Secret to your .env file

GitHub OAuth Setup

1. Go to GitHub Settings > Developer settings > OAuth Apps

2. Create a new OAuth App (or edit your existing one)

3. Set Authorization callback URL:

   • Development: http://localhost:3000/api/auth/callback/github
   • Production: https://yourdomain.com/api/auth/callback/github

   Note: This single callback URL handles both authentication and account linking. The system automatically detects which flow to use.

4. Copy the Client ID and Client Secret to your .env file

Important: The OAuth app is configured to request the repo scope, which allows creating GitHub issues. When users sign in with GitHub, they'll need to authorize your app to access their repositories.

Note: Users can sign in with Google and then link their GitHub account in the account settings to enable GitHub integration features. The account linking uses the same callback URL but with a special parameter to avoid changing the user's login method.

GitHub App Setup (Recommended)

Using a GitHub App lets Bug Buddy create issues as the app (not as each user) and receive webhook events for issue/comment sync.

Create the GitHub App

1. In GitHub, go to Settings → Developer settings → GitHub Apps and create a new app.
2. Webhook:
   • Webhook URL:
     • Development: http://localhost:3000/api/github/webhook
     • Production: https://yourdomain.com/api/github/webhook
   • Webhook secret: set this to GITHUB_APP_WEBHOOK_SECRET.
   • Subscribe to events:
     • ✅ Issues
     • ✅ Issue comment
3. Permissions (minimum):
   • Issues: Read & write
   • Metadata: Read-only
4. Install the app on the repositories you want Bug Buddy to create issues in.

Notes

• Users can still connect GitHub OAuth for repository browsing in the UI, but issue creation uses the GitHub App installation token.

Usage

1. Sign in with Google or GitHub at http://localhost:3000
2. If you signed in with Google, you'll be prompted to connect your GitHub account for integration features
3. Create a project in the dashboard
4. Copy the embed script from the project page
5. Add the script to your website
6. Configure GitHub integration in settings
7. Start receiving feedback!

Widget Embed

Add this script to your website:

<script
  src="http://localhost:3000/widget.js"
  data-project-key="YOUR_API_KEY"
  data-app-url="http://localhost:3000"
></script>

Replace YOUR_API_KEY with the API key from your project.

Available Scripts

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm start - Start production server
• pnpm db:generate - Generate Prisma client
• pnpm db:push - Push schema changes to database (development)
• pnpm db:migrate - Create and run migrations (production)
• pnpm db:studio - Open Prisma Studio