sarasin-bug-tracker

v1.0.22

Published

4 months ago

Standalone bug reporting component for Next.js with screenshot annotation and GitHub integration

0High
0Medium
0Low

sbonnell

bug-tracker nextjs react screenshot github issue-tracking annotation debugging

Bug Tracker Component

A standalone Next.js component for capturing bugs and suggestions with screenshots, annotations, and automatic GitHub issue submission.

Features

Floating Bug Button - Fixed position button in the bottom-right corner (keyboard shortcut: ALT + B)
Screenshot Capture - Full page or select specific areas
Annotation Tools - Add numbered markers, boxes, and highlights to screenshots
Multiple Screenshots - Capture and annotate multiple screenshots per report
React Component Detection - Automatically identifies React components and their source file locations
GitHub Integration - Automatically creates GitHub issues with screenshots uploaded to a separate repository
Version Display - Shows package version in the UI

Installation

NPM Package

npm install sarasin-bug-tracker

GitHub Package (Latest)

npm install sarasin-bug-tracker@github:Sarasin-and-Partners/BugTracker#v1.0.18

Usage

1. Create Server Actions File

Create app/actions/bugTrackerActions.ts (or similar location) and copy the contents from src/bugTrackerActions.ts:

'use server';

export { uploadScreenshotToGitHub, submitIssueToGitHub, checkGitHubConfig } from 'sarasin-bug-tracker/actions';

2. Add to Your Layout

import { BugTracker } from 'sarasin-bug-tracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <BugTracker />
      </body>
    </html>
  );
}

3. Configure Environment Variables

Add these to your .env.local file:

# Required: GitHub Personal Access Token for creating issues and uploading screenshots
GITHUB_ISSUES_TOKEN=ghp_your_token_here

# Required: Repository where issues and screenshots will be stored (format: owner/repo)
GITHUB_REPO=your-org/your-repo

# Optional: Branch name for screenshot uploads (defaults to 'main')
GITHUB_BRANCH=main

# Optional: Environment name for organizing screenshots (defaults to 'dev')
ENVIRONMENT=production

4. Configure Next.js Server Actions

Update your next.config.js to increase the body size limit for large screenshots:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '5mb', // Increase from default 1mb to handle large screenshots
    },
  },
}

module.exports = nextConfig

GitHub Setup

1. Create a GitHub Personal Access Token

For Fine-grained Personal Access Tokens (Recommended):

Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
Click "Generate new token"
Give it a descriptive name (e.g., "Bug Tracker - MyApp")
Set expiration (or choose "No expiration" for convenience)
Repository access: Select "Only select repositories" and choose your repo
Repository permissions:
- Issues: Read and write
- Contents: Read and write
Generate and copy the token

For Classic Personal Access Tokens:

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token (classic)"
Give it a descriptive name (e.g., "Bug Tracker - MyApp")
Select scopes:
- repo (Full control of private repositories) - for creating issues and uploading files
Generate and copy the token

2. Screenshot Storage

Screenshots are now stored in the same repository as your issues, organized in the following structure:

{GITHUB_REPO}/
  Bugtracker/
    {ENVIRONMENT}/
      {report-id}/
        screenshot.png

For Private Repositories:

Image URLs use GitHub's blob viewer (https://github.com/.../blob/main/...?raw=true)
Images are accessible to anyone with repository access
Links don't expire (unlike API download URLs)

For Public Repositories:

Image URLs use raw.githubusercontent.com
Images are publicly accessible
No authentication required

How to Use

Open Bug Tracker: Click the floating bug button (🐛) or press ALT + B
Select Type: Choose between "Bug" or "Suggestion"
Add Title (optional): Give your report a custom title
Capture Screenshots:
- Click "Full Page" to capture the entire page
- Click "Select Area" to capture a specific region
- Add multiple screenshots if needed
Annotate:
- Numbers: Add numbered markers to point out areas
- Box: Draw boxes (captures React component info)
- Delete: Remove the last annotation
Add Description: Describe the bug or suggestion
Submit to GitHub: Creates a GitHub issue with all screenshots and component details
- If screenshot upload fails, issue is still created with a warning message
- Success notification appears when complete

Screenshot Organization

Screenshots are organized in your repository at:

{GITHUB_REPO}/
  Bugtracker/
    {ENVIRONMENT}/
      {report-id}/
        screenshot.png

Example:

Sarasin-and-Partners/BugTracker/
  Bugtracker/
    production/
      1734567890123/
        screenshot.png
    dev/
      1734567890124/
        screenshot.png

Features in Detail

React Component Detection

When using the Box annotation tool or Select Area, the component automatically:

Detects all React components within the selected area
Captures component names, props, and hierarchy
Extracts source file locations (filename and line number)
Includes size and CSS class information

This works in development mode only as React debug information is stripped in production builds.

Compatibility:

✅ Next.js 14 with React 18
✅ Next.js 15 with React 19
✅ Webpack-internal paths are automatically cleaned

Multiple Screenshots

You can capture multiple screenshots per report:

Each screenshot can have its own annotations
Screenshots are uploaded individually to GitHub
All screenshots are embedded in the GitHub issue

Box Annotations

Box annotations capture React component information:

Draw a box around any area
Label the box for reference

GitHub Issue Format

Created issues include:

## Description
[User's description]

## Screenshots
![Screenshot](https://github.com/owner/repo/blob/main/Bugtracker/dev/report-id/screenshot.png?raw=true)

## Box Annotations
### Box 1: [Label]
- Component: Button
- Source: src/components/ui/button.tsx:15:3
- Size: 100x40
- Props: { variant: "primary", onClick: "ƒ()" }

## Context
- URL: https://example.com/page
- Viewport: 1920x1080
- User Agent: Mozilla/5.0...
- Timestamp: 2024-12-18T10:30:00.000Z
- React: 19.0.0

## Component Tree
[Detailed component hierarchy with source locations]

Error Handling: If screenshot upload fails (e.g., token permission issues), the issue is still created with a warning banner:

> ⚠️ **Screenshot Upload Failed:** GitHub token lacks permission to upload files. Issue will be submitted without screenshot.

[Rest of issue content...]

Component Tree

[Detailed component hierarchy with source locations]


## Development

### Build

```bash
npm run build

Environment Variables Summary

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITHUB_ISSUES_TOKEN | Yes | - | GitHub token for creating issues and uploading files | | GITHUB_REPO | Yes | - | Repository for issues and screenshots (owner/repo) | | GITHUB_BRANCH | No | main | Branch name for screenshot uploads | | ENVIRONMENT | No | dev | Environment name (dev/staging/prod) |

Troubleshooting

Screenshots not uploading

Error: "Resource not accessible by personal access token"

Fine-grained token: Ensure Repository access includes your repository
Fine-grained token: Verify Contents permission is set to "Read and write"
Classic token: Ensure repo scope is selected
Check that the token hasn't expired

Error: "Body exceeded 1 MB limit"

Add bodySizeLimit: '5mb' to your next.config.js under experimental.serverActions
Restart your development server

Screenshots not displaying in GitHub issues

For Private Repositories:

Images use GitHub blob URLs and require repository access to view
Viewers must be logged into GitHub with repository access
Links don't expire and work indefinitely

For Public Repositories:

Images use raw.githubusercontent.com URLs
No authentication required
Images are publicly accessible

Screenshot upload fails but issue still created

This is expected behavior! The system gracefully handles screenshot upload failures:

Issue is created successfully
Warning message appears in the UI
GitHub issue includes a warning banner explaining the screenshot couldn't be uploaded
Check token permissions (see above)

Source detection not working

Verify you're running in development mode (npm run dev, not npm run build)
Source information is only available with React's development build
Check browser console for any errors

Invalid GitHub token error

Ensure your token starts with ghp_, gho_, ghu_, ghs_, or ghr_
Verify the token has the correct permissions (Issues + Contents for fine-grained, or repo scope for classic)
Check that the token hasn't expired
For fine-grained tokens, verify repository access is grantede with React's development build
Check browser console for any errors

Invalid GitHub token error

Ensure your token starts with ghp_, gho_, ghu_, ghs_, or ghr_
Verify the token has the correct scopes (repo or public_repo)
Check that the token hasn't expired

License

MIT

Version

Current version: 1.0.18

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Bug Tracker Component

Features

Installation

NPM Package

GitHub Package (Latest)

Usage

1. Create Server Actions File

2. Add to Your Layout

3. Configure Environment Variables

4. Configure Next.js Server Actions

GitHub Setup

1. Create a GitHub Personal Access Token

For Fine-grained Personal Access Tokens (Recommended):

For Classic Personal Access Tokens:

2. Screenshot Storage

How to Use

Screenshot Organization

Features in Detail

React Component Detection

Multiple Screenshots

Box Annotations

GitHub Issue Format

Component Tree

Environment Variables Summary

Troubleshooting

Screenshots not uploading

Screenshots not displaying in GitHub issues

Screenshot upload fails but issue still created

Source detection not working

Invalid GitHub token error

Invalid GitHub token error

License

Version