feedback-kit

Drop-in React components for collecting structured user feedback as GitHub Issues — task-based testing sessions and ad-hoc bug reports. No external SaaS. No third-party data pipeline. Your GitHub repo is the backend.

---

Components

Component	What it is
<SessionPanel>	Slide-out panel — guided task walkthrough with typed steps (todo, rating, yes/no, question)
<FeedbackWidget>	Floating button — 4-step bug report form with screenshot capture and crop

Each submission creates a GitHub Issue. Three GitHub Actions workflows automate the downstream processing:

Workflow	Trigger	What it does
refine-feedback.yml	Auto	Rewrites raw [Feedback] bug reports into structured [Issue] tickets using GPT-4o
add-to-org-project.yml	Auto	Adds issues and PRs to your GitHub Projects v2 board
generate-user-stories.yml	Manual	Aggregates [Session] feedback by testing phase and task, and generates user story issues using GPT-4o

---

Install

Install directly from GitHub — no npm registry needed:

npm install github:THD-Spatial-AI/feedback-kit

To pin to a specific release tag or commit (recommended for production):

npm install github:THD-Spatial-AI/feedback-kit#v0.1.0
npm install github:THD-Spatial-AI/feedback-kit#abc1234

Your package.json will look like:

"@thd-spatial-ai/feedback-kit": "github:THD-Spatial-AI/feedback-kit"

---

Quick start

1. Deploy the API endpoint — copy api-templates/vercel.ts into your project's api/ directory and set four environment variables:

GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, BLOB_READ_WRITE_TOKEN

2. Copy the workflow templates — from workflow-templates/ into your repo:

.github/workflows/refine-feedback.yml       ← copy as-is, customise the system prompt
.github/workflows/add-to-org-project.yml    ← set your org and project number
.github/workflows/generate-user-stories.yml ← copy as-is
scripts/generate-user-stories.mjs           ← copy, then update the TASKS map

Add one secret: ADD_TO_PROJECT_PAT — a fine-grained PAT with Projects: read/write. No other secrets are needed; GITHUB_TOKEN is auto-provided.

3. Define your tasks — create a tasks.config.ts in your app:

import type { TestingTask } from '@thd-spatial-ai/feedback-kit'

export const myTasks: TestingTask[] = [
  {
    id: 'task-1',
    title: 'Find the settings panel',
    timeEstimate: '3–5 min',
    description: 'Start from the home screen and try to locate settings.',
    feedbackGoalHint: 'I was trying to find the settings panel.',
    steps: [
      { type: 'todo',   text: 'Locate the settings panel' },
      { type: 'rating', text: 'How easy was it?', lowLabel: 'Very hard', highLabel: 'Obvious' },
    ],
  },
]

3. Wrap your app and add components:

import { useState } from 'react'
import { FeedbackKitProvider, SessionPanel, FeedbackWidget } from '@thd-spatial-ai/feedback-kit'
import { myTasks } from './tasks.config'

export function App() {
  const [taskIndex, setTaskIndex] = useState(0)
  const [collapsed, setCollapsed] = useState(false)

  return (
    <FeedbackKitProvider apiEndpoint="/api/feedback">
      <YourContent />

      <SessionPanel
        tasks={myTasks}
        view="MyComponent"
        taskIndex={taskIndex}
        collapsed={collapsed}
        onToggleCollapsed={() => setCollapsed(c => !c)}
        onNextTask={() => setTaskIndex(i => i + 1)}
        onPrevTask={() => setTaskIndex(i => Math.max(0, i - 1))}
      />

      <FeedbackWidget view="MyComponent" />
    </FeedbackKitProvider>
  )
}

---

Extending

Add new step types without modifying the package:

import { defaultStepRenderers } from '@thd-spatial-ai/feedback-kit'

<FeedbackKitProvider
  stepRenderers={{ ...defaultStepRenderers, slider: MySliderStep }}
>

Intercept or enrich submissions:

<FeedbackKitProvider
  onBeforeSubmit={(payload) => ({ ...payload, context: `v${APP_VERSION}` })}
  onSubmitSuccess={({ issueNumber }) => analytics.track('feedback', { issueNumber })}
>

---

Self-hosting

The pipeline runs on any host. For Dokploy + MinIO setup, see Self-Hosting. The GitHub Issues + Actions layer is independent of where the app is hosted.

---

Documentation

Full documentation: thd-spatial-ai.github.io/feedback-kit

• Getting Started
• Session Panel
• Feedback Widget
• Custom Step Types
• Architecture
• API Reference

---

Reference implementation

The Building Configurator (EnerPlanET) is the reference consumer app — it demonstrates the full setup including task config, Vercel deployment, and GitHub Actions workflows.