the-controller-feedback-widget

Files (1)

• SKILL.md

SKILL.md (first lines)

# Feedback Widget

Set up a floating feedback button that lets users capture a screenshot, annotate it (freehand draw, arrows, rectangles, crop), and submit it as a GitHub issue — all without leaving the app.

## Prerequisites

- **Next.js App Router** project (13+)
- **shadcn/ui** installed (Button, Sheet components)
- **lucide-react** installed

## Setup Steps

### 1. Understand the target project

Before writing any code, determine:

- **Auth system**: How does the project authenticate users? (Supabase, NextAuth, Clerk, custom JWT, none)
- **UI components path**: Where are shadcn components? (usually `src/components/ui/` or `components/ui/`)
- **App metadata**: What project-specific context should be captured with feedback? (current page URL is always captured; additional context like selected items, user settings, etc. is project-specific)

### 2. Install dependencies

```bash
npm install html2canvas-pro
# or: pnpm add html2canvas-pro / bun add html2canvas-pro
```

Ensure these shadcn components are installed:
```bash
npx shadcn@latest add button sheet
```

### 3. Create the AnnotationEditor component

Create `annotation-editor.tsx` in the project's component directory.

This component is **fully portable** — copy it verbatim from `## AnnotationEditor Reference` below. It has no project-specific dependencies beyond shadcn `Button` and lucide icons.

Key features:
- Dual-canvas architecture (base image + draw overlay) for efficient rendering
- Tools: freehand draw, arrow, rectangle, crop
- Undo/clear via ImageData history stack
- Retina display support via `devicePixelRatio`
- Outputs a single composited PNG data URL on "Done"

### 4. Create the FeedbackButton component

Create `feedback-button.tsx` in the project's component directory. This needs **project-specific adaptation**:

**Auth gating**: Replace the auth check with the project's auth system:

```tsx
// Supabase example
const supabase = createClient();
const { data: { user } } = await supabase.auth.getUser();
setIsAuthenticated(!!user);

// NextAuth example
const { data: session } = useSession();
setIsAuthenticated(!!session);

// Clerk example
const { isSignedIn } = useUser();
setIsAuthenticated(isSignedIn ?? false);

// No auth (always show)
setIsAuthenticated(true);
```

**Metadata collection**: Adapt the metadata object in `handleSubmit` to capture project-relevant context. Always include:
- `url` — current page path + query params
- `viewport` — window dimensions
- `userAgent` — browser string

Add any project-specific context (selected items, active filters, user role, etc.).

**Reference implementation:** See `## FeedbackButton Reference` below.

### 5. Create the API route

Create the API route at `app/api/feedback/route.ts`.

This route:
1. Validates the user is authenticated (adapt auth check to project's system)
2. Uploads the screenshot PNG to the GitHub repo's `.feedback/` directory via GitHub Contents API
3. Creates a GitHub issue with description, embedded screenshot, and metadata

**Auth check adaptation**: Same as step 4 — use the project's server-side auth.

**Reference implementation:** See `## API Route Reference` below.

### 6. Set environment variables

Add to `.env` (or `.env.local`):

```
GITHUB_TOKEN='ghp_...'
GITHUB_FEEDBACK_REPO='owner/repo'
```

The GitHub token needs `repo` scope (to create issues and upload files).

**Important**: These are server-only variables (no `NEXT_PUBLIC_` prefix). Never expose the GitHub token to the client.

### 7. Wire up in layout

Add `FeedbackButton` to the root layout, wrapped in `<Suspense>` (it uses `useSearchParams`):

```tsx
import { Suspense } from "react";
import { FeedbackButton } from "@/components/feedback-button";

// Inside the layout body, before closing </body>:
<Suspense>
  <FeedbackButton />
</Suspense>
```

### 8. Add the feedback label to GitHub

From kwannoel/the-controller, MIT.

More from kwannoel/the-controller