Standalone bug reporting component for Next.js with screenshot annotation and GitHub integration
npm install sarasin-bug-trackerbash
npm install sarasin-bug-tracker
`
$3
`bash
npm install sarasin-bug-tracker@github:Sarasin-and-Partners/BugTracker#v1.0.18
`
Usage
$3
Create app/actions/bugTrackerActions.ts (or similar location) and copy the contents from src/bugTrackerActions.ts:
`typescript
'use server';
export { uploadScreenshotToGitHub, submitIssueToGitHub, checkGitHubConfig } from 'sarasin-bug-tracker/actions';
`
$3
`tsx
import { BugTracker } from 'sarasin-bug-tracker';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
`
$3
Add these to your .env.local file:
`bash
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
`
$3
Update your next.config.js to increase the body size limit for large screenshots:
`javascript
/* @type {import('next').NextConfig} /
const nextConfig = {
experimental: {
serverActions: {
bodySizeLimit: '5mb', // Increase from default 1mb to handle large screenshots
},
},
}
module.exports = nextConfig
`
GitHub Setup
$3
#### For Fine-grained Personal Access Tokens (Recommended):
1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click "Generate new token"
3. Give it a descriptive name (e.g., "Bug Tracker - MyApp")
4. Set expiration (or choose "No expiration" for convenience)
5. Repository access: Select "Only select repositories" and choose your repo
6. Repository permissions:
- Issues: Read and write
- Contents: Read and write
7. Generate and copy the token
#### For Classic Personal Access Tokens:
1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Bug Tracker - MyApp")
4. Select scopes:
- repo (Full control of private repositories) - for creating issues and uploading files
5. Generate and copy the token
$3
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
1. Open Bug Tracker: Click the floating bug button (🐛) or press ALT + B
2. Select Type: Choose between "Bug" or "Suggestion"
3. Add Title (optional): Give your report a custom title
4. Capture Screenshots:
- Click "Full Page" to capture the entire page
- Click "Select Area" to capture a specific region
- Add multiple screenshots if needed
5. Annotate:
- Numbers: Add numbered markers to point out areas
- Box: Draw boxes (captures React component info)
- Delete: Remove the last annotation
6. Add Description: Describe the bug or suggestion
7. 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
$3
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
$3
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
$3
Box annotations capture React component information:
- Draw a box around any area
- Label the box for reference
GitHub Issue Format
Created issues include:
`markdown
Description
[User's description]
Screenshots
!Screenshot
Box Annotations
$3
- 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:
`markdown
> ⚠️ 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
$3
`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
$3
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
$3
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
$3
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)
$3
- 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
$3
- 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
$3
- Ensure your token starts with ghp_, gho_, ghu_, ghs_, or ghr_
- Verify the token has the correct scopes (repo or public_repo`)