Configuration.

Pass your project key and any options when you initialize pinthread.

YOUR_PROJECT_KEY is a placeholder for a string. For hosted pinthread, copy the key returned by pinthread init. For self-hosting, use the project identifier configured on your server. Reuse the same key wherever you want to share feedback.

import { initPinthread } from 'pinthread';

initPinthread({
  project: 'YOUR_PROJECT_KEY',
  pageRoot: document.querySelector('#app'),
  scope: 'branch',
  branch: 'preview/navigation',
});

Client options

Option	Type	Default / behavior
`endpoint`	`string`	Hosted pinthread API by default. Override for self-hosting.
`project`	`string`	Required. Use the string returned by setup. Public, not a credential.
`repo`	`string`	Defaults to the project key. Pass owner/repo to enrich agent prompts.
`scope`	`"project" \| "branch"`	project: feedback shared across deployments. Use branch to isolate it.
`branch`	`string`	Detected at build time by pinthread sync when branch scope is enabled.
`enabled`	`boolean`	true. Set false to omit the widget.
`pageRoot`	`HTMLElement`	Mounted content root for Frame. Defaults to a sole existing content element; multiple roots use Floating until pageRoot is set.
`page`	`() => string`	Current pathname. Query strings and fragments excluded.
`drawerContainer`	`HTMLElement`	Optional element to center the drawer within.
`autoHideDrawer`	`boolean`	true. Set false to keep the drawer visible.
`sidebar`	`"background" \| "edge"`	"edge" (default) is a floating sidebar. "background" frames the page. Account → Sidebar switches Floating and Frame.
`pollInterval`	`number`	4000 ms while the page is visible.
`source`	`(element: Element) => string \| undefined`	Element → repository-relative source file path.
`sourceUrl`	`(source: string, branch: string) => string`	Source path and branch → editor or repository URL.
`sessionDomain`	`string`	Optional parent domain you own. Never a public suffix.

Branch scope

npx pinthread init --branch-scope

Use this when feedback belongs to a particular change. Without it, matching page paths share comments across deployments.

For automatic branch detection, import initPinthread from the optional generated pinthread.config.js helper and run pinthread sync before your build. It checks deployment environment variables and Git. Set PINTHREAD_BRANCH when neither can identify the branch.

Source links

initPinthread({
  project: 'YOUR_PROJECT_KEY',
  source: element => element.closest('[data-source]')
    ?.getAttribute('data-source') ?? undefined,
});

Add data-source="src/components/Hero.tsx" to an element to include that file in copied feedback. Source references are provided by your site; pinthread does not upload your code.

Lifecycle

const review = initPinthread({ project: 'YOUR_PROJECT_KEY' });
review.open();    // Open the sidebar
review.close();   // Close it
await review.refresh();
review.destroy();

Destroy the instance when your application unmounts. Repeated initialization in the same document reuses the existing instance.