@commentkit/comment-kit

CommentKit

Figma-style comments for any website.

Your clients click the part of the page they mean and write what should change. CommentKit pins the comment to that exact spot, attaches a screenshot of what they saw, and records the page, browser and screen size. You see the feedback on your live site, your staging and preview links, and on localhost — and you can hand it straight to your AI coding agent.

• One install, every stack. A script tag works on any website (WordPress, Webflow, Shopify, plain HTML). npm users get init() plus tiny React, Vue and Svelte helpers. Nothing else to install: no React required on your side.
• Built for people who have never used a feedback tool. Clients open a client link, click, type, confirm their email once. No account, no password.
• Built for developers. Feedback per branch and environment, element selectors and source locations, console errors, a dashboard with list and board views, email notifications, and an MCP server for Claude Code, Cursor and other agents.

Install

Any website

Paste before </body>:

<script src="https://commentkit.dev/cdn/v1/loader.js" data-project="pk_live_your_key" defer></script>

npm

npm install @commentkit/comment-kit

import { init } from "@commentkit/comment-kit";

init({ project: "pk_live_your_key" });

React / Next.js

import { CommentKit } from "@commentkit/comment-kit/react";

// Root layout, next to {children}. Works in Next.js server layouts.
<CommentKit project="pk_live_your_key" branch={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF} />

Vue / Nuxt

import { CommentKitPlugin } from "@commentkit/comment-kit/vue";

app.use(CommentKitPlugin, { project: "pk_live_your_key" });

Nuxt: create plugins/commentkit.client.ts:

import { CommentKitPlugin } from "@commentkit/comment-kit/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(CommentKitPlugin, { project: useRuntimeConfig().public.commentkitKey });
});

Or place <CommentKit project="pk_live_your_key" /> from @commentkit/comment-kit/vue once in your root component; it accepts every option below as a prop.

Svelte / SvelteKit

<!-- src/routes/+layout.svelte -->
<script>
  import { commentkit } from "@commentkit/comment-kit/svelte";
  let { children } = $props();
</script>

<svelte:body use:commentkit={{ project: "pk_live_your_key" }} />
{@render children()}

Anything else

Angular, Solid, Astro, Qwik, Remix, or a custom setup: call init() once in the browser. If you prefer markup, import the custom element once in your bundle and place the tag anywhere:

import "@commentkit/comment-kit/element";

<comment-kit project="pk_live_your_key" branch="main"></comment-kit>

Attributes: project (required), branch, commit, locale, theme, position, auth, endpoint, deployment-url, hide-on-production="false", shortcuts="false". Changing project restarts the widget.

Find your key in the dashboard under Project → Setup (or run npx @commentkit/cli login and then npx @commentkit/cli init, or npx @commentkit/cli init --key pk_live_… without signing in), and add every website address there (live, staging, preview, e.g. https://*.vercel.app). Localhost always works for your team.

How it behaves

People leave feedback with one tool:

• Click an element to comment on it.
• Drag to mark an area.
• Select text first to comment on exactly that text.

A screenshot of the visible page is attached automatically with the pin drawn on it. Reviewers can draw on it (arrow, box, pen, blur to hide private details, text). Passwords, card fields, one-time codes and anything marked data-commentkit-redact are never captured.

Sign-in opens a small CommentKit window (or continues in the same tab inside in-app browsers like WhatsApp and Instagram). Credentials never touch your page.

Options

init({
  project: "pk_live_…",        // required
  branch: "feature/checkout",  // filter feedback per branch
  commit: "a1b2c3d",
  deploymentUrl: "https://pr-12.example.vercel.app",
  hideOnProduction: true,      // default; false shows the launcher to everyone
  theme: "auto",               // "light" | "dark" — default from the dashboard
  position: "bottom-right",
  redact: [".customer-email"], // extra selectors never captured
  locale: "fr",                // default: <html lang>, then the browser (see Languages)
  auth: "auto",                // "popup" | "redirect"
  shortcuts: true,             // false turns off C, J / K, E and ? (Esc and Cmd/Ctrl+Shift+K stay)
});

Most behaviour is set in the dashboard and applies instantly without a deploy: pausing feedback on all sites, theme, position, accent colour, privacy selectors, and console/network capture.

Script-tag attributes

data-project (required), data-branch, data-commit, data-locale, data-auth, data-endpoint (another CommentKit server), data-hide-on-production="false", data-shortcuts="false". theme, position, redact and deploymentUrl are init() options; theme, position and privacy selectors can also be set in the dashboard.

Languages

The widget speaks English, Spanish (es), French (fr), German (de), Portuguese for Brazil (pt-BR), Italian (it), Dutch (nl), Japanese (ja), Chinese, Simplified (zh-CN), Hindi (hi) and Arabic (ar, right to left).

It picks the first match from init({ locale }) (or data-locale / <comment-kit locale>), then the page's <html lang>, then the reader's browser languages, and falls back to English. Regions fall back to the language: es-MX gets Spanish, pt and pt-PT get Brazilian Portuguese, zh gets Simplified Chinese. Times ("5 minutes ago") and counts use the browser's Intl formatting for that language.

English is built in. Each other language is a separate ~2.5–3 KB (gzip) file, loaded only for readers who need it, while the widget starts. The widget is right to left when its language is Arabic, and otherwise follows the page's dir or <html lang>.

Only the widget is translated; the dashboard and emails are in English for now.

API

init() returns an instance:

const kit = init({ project: "pk_live_…" });

kit.show();               // same as Cmd/Ctrl + Shift + K
kit.hide();
kit.open("CK-12");        // show the widget and open one conversation (id or reference)
await kit.signIn();       // call from a click
await kit.signOut();
kit.session();            // { person, role, project, environment, capabilities } | null
kit.on("thread:created", ({ thread }) => {});
kit.destroy();            // removes every trace from the page

Events: ready, session:change, thread:created, thread:updated, message:created, and error (the widget could not start; error.code is listed at https://commentkit.dev/docs/errors).

Script tag API: window.CommentKit

On sites that use the script-tag loader, the loader sets one global once the widget is ready, window.CommentKit, and destroy() removes it again. It is the only global CommentKit adds; npm installs use the init() instance instead.

CommentKit.version;                          // "1.0.0"
CommentKit.show();                           // Promise
CommentKit.hide();
CommentKit.open("CK-12");                    // or a thread id
const onNew = ({ thread }) => console.log(thread.reference);
CommentKit.on("thread:created", onNew);
CommentKit.off("thread:created", onNew);
CommentKit.destroy();                        // removes the widget, its listeners and window.CommentKit

window.CommentKit only exists while the widget is shown on that page (local development, a share or email link, a signed-in person, or after Cmd/Ctrl + Shift + K). Check for it before calling: window.CommentKit?.open("CK-12").

Nothing CommentKit does can break your page: a failed download, a setup error or a crash inside the widget logs one console warning and the widget removes itself.

@commentkit/comment-kit/headless exports CommentKitClient, createAnchor and resolveAnchor for custom interfaces and browser extensions.

AI agents

The easiest way: add https://commentkit.dev/mcp as a remote MCP server in Claude, Cursor or VS Code and sign in. You choose the project and what the agent may do.

claude mcp add --transport http commentkit https://commentkit.dev/mcp

Or run the server on your computer: create an agent token in Project → Developers, then add it to your agent:

{
  "mcpServers": {
    "commentkit": {
      "command": "npx",
      "args": ["-y", "comment-kit-mcp"],
      "env": { "COMMENT_KIT_PROJECT_ID": "123", "COMMENT_KIT_ACCESS_TOKEN": "…" }
    }
  }
}

Agents can list, search and read feedback and dashboard tasks (including the screenshot, by id or CK-12). With the permissions you choose, they can reply, link the commit and mark a task ready for review; by default a person approves each of these first (Agent requests). The reviewer then checks and resolves it. Agents never resolve, assign or delete. See mcp/README.md.

Terminal and build tools

• @commentkit/cli: commentkit login (a short code confirmed in the browser), init (adds the key, the build plugin and .gitignore entry), pull (open feedback to .commentkit/feedback.md for any agent), open CK-12, and tokens for CI.
• @commentkit/build: Vite, Next.js, webpack and Astro plugins that tag elements with their source file and line in development, and record the branch and commit. On localhost the widget then shows this branch's feedback first, with "All branches" one click away.

Privacy and security

• The project key (pk_…) only identifies a project. Everything is authorised on the server: the widget only works on the websites you list, sessions are bound to that website, and reviewers only see projects they were invited to.
• The widget runs in a Shadow DOM, adds one element to your page, needs no unsafe-eval, and removes itself completely on destroy().
• Trusted Types: the widget works under require-trusted-types-for 'script'. The screenshot engine writes two fixed strings through one narrowly named policy, commentkit-capture, that accepts nothing else; no default policy is created. If your CSP limits policy names with trusted-types, add commentkit-capture (without it, screenshots are skipped and everything else works).
• Console and network capture are off unless the project turns them on, and then each reviewer chooses per comment ("Include browser errors to help the developer"). Only metadata is kept (message; or method, URL, status, timing for fetch and XMLHttpRequest), never bodies or headers, and credential-looking values are removed from URLs and text by name and by value. "Copy for AI agent" removes them too.
• Feedback text is rendered as plain text with safe links only. Agent output marks feedback as untrusted.
• See SECURITY.md for hardening guidance and how to report a vulnerability.

Size

Versioning and support

CommentKit follows semantic versioning: a patch fixes bugs, a minor adds options or features without breaking anything, and only a new major version may remove or change behaviour. init() options, the instance API, events, data-* attributes, the custom element and the adapters are the public API. The look of the widget and its wording can improve in any release.

Script tag channels

To pin, use the exact version and its Subresource Integrity hash, so the browser refuses the file if it ever differs. The hashes for every published version are in https://commentkit.dev/cdn/integrity.json (served from public/cdn/integrity.json in the backend):

<script src="https://commentkit.dev/cdn/1.2.3/loader.js" integrity="sha384-…" crossorigin="anonymous" data-project="pk_live_your_key" defer></script>

The loader then loads the rest of the widget from the same pinned folder, which is immutable. A pinned version gets no fixes: move to a newer one on purpose, and check its changelog first.

npm: npm install @commentkit/comment-kit@^1 follows 1.x the same way as /cdn/v1; use an exact version (--save-exact) and your lockfile to pin. Release candidates for a future major are published under the next tag and are never installed by ^1. The full rules are in docs/VERSIONING.md.

Support window: each major version gets security fixes for 24 months after the next major version is released, and bug fixes until then. The end date of each major is announced in the changelog when its successor ships. Security fixes land in the latest minor of every supported major, so the moving channel and ^ ranges receive them automatically; pinned versions do not. See SECURITY.md to report a vulnerability.

Development

npm ci
npm run typecheck
npm test               # unit tests (Vitest)
npm run build          # npm + CDN bundles, public types, size budgets
npm run test:e2e       # Playwright: Chromium, Firefox, WebKit
npm run test:visual    # screenshot tests of the main widget states (Chromium; baselines recorded on macOS)
npm run test:host-matrix   # packed SDK in Next.js, Nuxt, SvelteKit, Angular, Astro, React Router, HTML, WordPress (slow)
semgrep scan --config .semgrep.yml --error src   # security rules for the widget (brew install semgrep)
npm run ci             # every gate; HOST_MATRIX=1 npm run ci adds the host matrix

Locally Playwright reuses an e2e server already running on port 5190; when several checkouts (git worktrees) test at once, give each its own with CK_E2E_PORT=5291 npm run test:e2e. Screenshot baselines live in e2e/specs/visual.spec.ts-snapshots/. After an intended visual change, update them with npx playwright test e2e/specs/visual.spec.ts --project=chromium --update-snapshots and review the new images before committing. The host matrix (scripts/host-matrix.mjs) installs the npm pack tarball into each app in e2e/host-matrix/, builds it for production and checks that the widget mounts once on localhost with no console errors, and that single-page apps destroy it on a route without it. Pass app names to run some of them (npm run test:host-matrix -- next astro); WordPress needs php on the PATH and is skipped without it.

The architecture and roadmap live in ARCHITECTURE-BLUEPRINT.md and TASKS.md.

Releasing

Versions and changelogs are managed with Changesets for the four published packages: @commentkit/comment-kit (this folder), comment-kit-mcp (mcp/), @commentkit/cli (cli/) and @commentkit/build (build/). The browser extension, the Zapier app and the Make app are private and never versioned this way. There are no npm workspaces: each package keeps its own lockfile, and lerna.json only tells Changesets where the packages are.

1. With every change that people using a package will notice, add a changeset: npm run changeset. Pick the packages, the bump (patch, minor or major, see Versioning above) and write one plain sentence for the changelog. Commit the file in .changeset/ with the change.

2. To prepare a release, run npm run release:status to see what will be bumped, then npm run version. It applies the bumps to each package.json and writes the changelogs. Review the diff, update each package's lockfile (npm install --package-lock-only in that folder), and commit.

3. While 1.x is in beta, run npx changeset pre enter beta once first, so versions come out as 1.0.0-beta.N instead of jumping to 1.0.0; npx changeset pre exit before the stable release.

4. Publishing stays manual and needs the owner's go-ahead each time: in each package folder, npm run check (or that package's gates) and node scripts/check-pack.mjs, then npm publish. Do not run changeset publish.

5. The CDN widget rolls out gradually. In the backend, scripts/sync-sdk.sh writes the pinned public/cdn/<version>/ folder (with SRI hashes); deploy it, then php artisan cdn:canary <version> --percent=1, later 10 and 100. The /cdn/v1/ loader asks /api/v1/widget/channel which version to load, so a change takes effect within a minute. Widget crashes are counted per version, and the canary is rolled back automatically when it crashes in more than 1% of loads or three times as often as stable (cdn:canary --status, --rollback by hand). When it has held at 100%, sync it into /cdn/v1/ (the stable files), deploy, and cdn:canary --clear.

npm run version is also npm's lifecycle hook for npm version, so npm version in this folder runs Changesets too; use the steps above instead of npm version.

License

Proprietary. See LICENSE.