<gh-feedback>

Setup

1. Add the component to your page

Copy gh-feedback.js into your project and add to your HTML:

<script type="module" src="gh-feedback.js"></script>
<gh-feedback
  repo="https://github.com/you/repo"
  endpoint="https://your-worker.workers.dev/feedback"
></gh-feedback>

A hosted copy is also available as a convenience:

<script type="module" src="https://gh-feedback.synapticnoise.com/gh-feedback.js"></script>

2. Deploy a proxy backend

The component needs a backend to securely file GitHub Issues (so your token stays server-side). See Proxy Setup below, or use any backend that accepts the JSON payload.

Attributes Reference

Proxy Setup (Recommended)

The proxy keeps your GitHub token on the server. Users never see it. The included backend runs on Cloudflare Workers (free tier) and deploys with Wrangler, Cloudflare's CLI tool.

1. Prerequisites

• Node.js 18+ and npm
• A Cloudflare account (free tier works)

2. Log in to Cloudflare

Wrangler is the CLI for Cloudflare Workers. You don't need to install it separately — npx runs it directly. Log in to connect it to your Cloudflare account:

npx wrangler login

This opens your browser for authentication. Once approved, Wrangler stores your credentials locally.

3. Create the worker

Copy the worker/ directory from this repo into your project, or start fresh:

mkdir gh-feedback-worker && cd gh-feedback-worker
cp -r /path/to/gh-feedback/worker/* .
npm init -y

4. Configure the worker

Open wrangler.toml and set these two values:

• GITHUB_REPO — change "owner/repo" to your GitHub repository (e.g., "acme/webapp")
• ALLOWED_ORIGINS — change "*" to your website's URL (e.g., "https://your-site.com"). During development, include localhost too: "https://your-site.com,http://localhost:3000". The default * allows any site — restrict before going live

5. Create a GitHub token

Create a fine-grained Personal Access Token:

1. Go to github.com/settings/tokens
2. Click Generate new token
3. Name it something descriptive, e.g., gh-feedback-proxy
4. Under Repository access, select Only select repositories and choose the repo
5. Under Permissions > Repository permissions, set Issues to Read and Write
6. Click Generate token and copy it

Then store it as a secret in your worker (secrets are encrypted and never appear in plain text). Run this from the worker directory created in step 3:

npx wrangler secret put GITHUB_TOKEN
# Paste the token when prompted

6. Deploy

npx wrangler deploy

Wrangler prints the worker URL, e.g., https://gh-feedback-proxy.your-account.workers.dev.

7. Use it

<gh-feedback repo="https://github.com/you/repo" endpoint="https://gh-feedback-proxy.your-account.workers.dev/feedback"></gh-feedback>

8. Verify

curl -X POST https://gh-feedback-proxy.your-account.workers.dev/feedback \
  -H "Content-Type: application/json" \
  -d '{"title": "Test issue from curl", "type": "bug"}'

You should get back {"issueNumber": ..., "issueUrl": "..."} and see the issue in your GitHub repo.

Multi-repo note: The worker always files issues to the repo configured in GITHUB_REPO. To file to multiple repos, deploy one worker per repo.

Alternative Backends

The component POSTs JSON to any URL. The worker/ template is for Cloudflare Workers, but any backend works. The contract:

POST { title, type, severity?, description, labels?, repo?, context? }
--> 201 { issueNumber, issueUrl }
--> 4xx/5xx { error: "message" }

Your backend receives this JSON, creates a GitHub Issue using a server-side token, and returns the result. The key requirement is that the endpoint holds the GitHub token server-side -- it never reaches the browser.

Any of these work:

• Vercel Functions -- api/feedback.js with GITHUB_TOKEN env var
• Netlify Functions -- netlify/functions/feedback.js
• AWS Lambda -- behind API Gateway
• Deno Deploy -- single main.ts file
• Express / Flask / Rails -- any traditional server
• Any serverless platform -- anything that can receive a POST and call the GitHub API

The Cloudflare Worker in worker/ is a good reference implementation (~80 lines). Adapt it to your platform.

Direct Mode

If you don't want to set up a proxy, you can pass a GitHub token directly:

<gh-feedback repo="https://github.com/you/repo" token="ghp_yourTokenHere"></gh-feedback>

Events

Listener example

document.querySelector('gh-feedback')
  .addEventListener('gh-feedback:filed', (e) => {
    console.log(`Issue #${e.detail.issueNumber}: ${e.detail.issueUrl}`);
  });

Context Capture

Set the getContext property to a function that returns an object. The data is attached to the issue body in a collapsible details section.

const fb = document.querySelector('gh-feedback');
fb.getContext = () => ({
  url: location.href,
  viewport: `${innerWidth}x${innerHeight}`,
  userAgent: navigator.userAgent,
  timestamp: new Date().toISOString()
});

TypeScript

Type definitions are included in gh-feedback.d.ts. Event listeners are fully typed:

import type { GhFeedback } from './gh-feedback';

const fb = document.querySelector('gh-feedback')!;

fb.addEventListener('gh-feedback:filed', (e) => {
  console.log(e.detail.issueNumber); // number
});

fb.addEventListener('gh-feedback:error', (e) => {
  console.error(e.detail.error); // string
});

Exported types: FeedbackType, Severity, TriggerStyle, Position, Theme, IconName, Size, SubmitDetail, FiledDetail, ErrorDetail, GhFeedbackEventMap.

Theming

For fine-grained control beyond the color attribute, override CSS custom properties on the gh-feedback element:

<style>
  gh-feedback {
    --gh-feedback-primary: #6f42c1;
    --gh-feedback-primary-hover: #8250df;
  }
</style>
<gh-feedback repo="https://github.com/you/repo" endpoint="..." theme="dark"></gh-feedback>

Security & CSP

Proxy mode (recommended): Your GitHub token stays on the server. The browser only communicates with your worker endpoint.

Direct mode: The token is in the HTML source. Only for internal tools or pages behind auth.

If your site uses a strict Content Security Policy, add the proxy endpoint to connect-src:

Content-Security-Policy: connect-src 'self' https://your-worker.workers.dev;

Shadow DOM <style> elements are CSP-exempt in modern browsers, so no style-src changes are needed.

Development

Run the unit tests (worker):

npm install
npm test

Run the Playwright E2E tests:

npx playwright install --with-deps chromium
npx playwright test

Run all tests:

npm run test:all

License

MIT -- use it anywhere.