pinpoint-feedback
v0.6.0
Published
Visual website feedback widget with screenshot annotation. Reports go straight into your Notion database.
Maintainers
Readme
Pinpoint Feedback
Visual website feedback that lands in Notion. Visitors click a button, get a screenshot of the page, mark it up with pins, arrows, boxes, freehand and text, black out personal data with redaction boxes, and send it. Each report becomes a page in your Notion database with the original and annotated screenshots attached. Notion is the only backend.
Live demo → pinpoint-feedback.dwrth.dev
Browser Your server route Notion
widget → screenshot → annotate ─POST─▶ validate · rate-limit · dedupe ─API─▶ database page
◀─JSON─ upload files · create page ◀──── + 2 imagesInstall
npm install pinpoint-feedbackPeer dependencies: react/react-dom 18.2+ for the widget, next 14.2+ for the Next.js entry points.
Quick start (Next.js App Router)
Create a Notion integration, share a database with it and set the env vars (full walkthrough):
NOTION_API_KEY=ntn_... NOTION_FEEDBACK_DATABASE_ID=0123456789abcdef0123456789abcdefRender the widget in
app/layout.tsx(works from a Server Component):import { FeedbackProvider } from "pinpoint-feedback/nextjs"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> {children} <FeedbackProvider position="bottom-right" theme="light" /> </body> </html> ); }Add the endpoint in
app/api/feedback/route.ts:import { createFeedbackHandler } from "pinpoint-feedback/nextjs/server"; export const runtime = "nodejs"; export const POST = createFeedbackHandler();
Missing database columns are created on the first submission. A working app lives in examples/nextjs-app, deployed at pinpoint-feedback.dwrth.dev.
Custom categories and languages are shared between the layout and the route through one config file (categories, i18n):
// feedback.config.ts — import from the root entry so server code can use it
import { defineCategories } from "pinpoint-feedback";
import { de } from "pinpoint-feedback/locales/de";
export const categories = defineCategories(["bug", { id: "perf", label: "Performance", color: "orange" }]);
export const locale = de;<FeedbackProvider categories={categories} defaultCategory="perf" locale={locale} /> // layout
export const POST = createFeedbackHandler({ categories, locale }); // routeBuilt-in languages: English, German, French, Spanish, Italian, Portuguese (Brazil), Dutch, Polish, Japanese, Chinese (Simplified), Arabic (RTL).
Docs
| Topic | |
| --- | --- |
| Getting started | Notion integration, database, env vars, troubleshooting |
| Widget | FeedbackProvider / FeedbackWidget props, useFeedback, theming |
| Server handler | Handler options, status codes, CORS, rate limiting, security |
| Notion | Database properties, schema auto-setup, page layout, file uploads |
| Categories | defineCategories, type-safe ids, Notion select options |
| Internationalization | Built-in locales, negotiation, overrides, RTL, report language |
| Screenshots | How capture works, what can't be captured, screen-capture fallback |
| Annotation editor | Tools, shortcuts, zoom/pan, data model, standalone usage |
| Reliability | Submission IDs, duplicate protection, offline outbox, retries |
| Other frameworks | Web Request/Response handler, React without Next, vanilla JS |
| Architecture | Packages, entry points, DI interfaces, data flow |
| Development | Monorepo, tests, e2e, CI, releasing |
Entry points
| Import | Use |
| --- | --- |
| pinpoint-feedback | Core (framework-free): capture, annotation editor, client, defineCategories, defineLocale |
| pinpoint-feedback/nextjs | FeedbackProvider, FeedbackWidget, useFeedback (client) |
| pinpoint-feedback/nextjs/server | createFeedbackHandler (server-only) |
| pinpoint-feedback/react | Widget for React apps without Next.js |
| pinpoint-feedback/server | createFeedbackRequestHandler for any Web Request/Response runtime |
| pinpoint-feedback/locales/<tag> | Language bundles, e.g. locales/de, locales/pt-BR |
The dialog shows a privacy notice above the send button (what is sent, where it is stored), translated in every built-in language; reword it, link your privacy policy with privacyPolicyUrl or turn it off with privacyNotice={false}.
The Notion token is only ever read on the server; pinpoint-feedback/nextjs/server imports server-only so it can't end up in a client bundle.
Development
npm install
npm run build # all packages
npm test # vitest (core, server, react, nextjs, scripts)
npm run test:coverage # with enforced coverage thresholds
npm run typecheck
npm run e2e # Next.js example + mock Notion API + PlaywrightSee Development for the example app, the mock Notion server and CI.
