comment mode

Embeddable commenting for live prototypes (Next.js / React).

Install

npm install comment-mode

Minimal setup

The fastest way to get started is the Commentator wrapper. It wires up the provider, commentable surface, and overlay for you.

import { Commentator } from "comment-mode";

function App() {
  return (
    <Commentator
      config={{
        projectSlug: "my-prototype",
        surfaceId: window.location.pathname,
        github: {
          owner: "your-github-user-or-org",
          repo: "your-repo-name",
        },
      }}
    >
      {/* Your prototype UI. Clicks here create comment pins when comment mode is on. */}
    </Commentator>
  );
}

Example: Next.js app layout

Here’s a more complete example that mirrors the prototype demo, including a surfaceId based on pathname + search params and a custom API base URL.

import React from "react";
import { usePathname, useSearchParams } from "next/navigation";
import { Commentator } from "comment-mode";


export function CommentatorLayout({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();
  const surfaceId = [
    pathname ?? "/",
    searchParams?.toString() ? `?${searchParams.toString()}` : "",
  ].join("");

  return (
    <Commentator
      config={{
        projectSlug: "my-prototype",
        surfaceId,
        github: {
          owner: "your-github-user-or-org",
          repo: "your-repo-name",
        },
      }}
      position="right"
      surfaceClassName="min-h-screen flex flex-col"
    >
      {children}
    </Commentator>
  );
}

Required config

• projectSlug (required) — Identifies your project (e.g. "my-prototype").
• surfaceId (required) — Identifies the page/screen/surface (e.g. window.location.pathname or pathname + search).

Optional extras

• position — "left" or "right" for where the comment panel appears (default "right").
• apiBaseUrl — Override the Comment Mode API base URL (only needed if you are self‑hosting the API).
• pageUrl — Full URL of the current page (e.g. window.location.href). Used when creating GitHub issues so the issue body can link back to the prototype.
• github — GitHub integration for turning comment threads into issues:
  • owner (required if github is set) — GitHub org or username.
  • repo (required if github is set) — Repository name.
  • createIssueForNewThreads — When true, every new comment thread automatically creates a GitHub issue. Default is false (opt-in). When false, users can still create an issue from a thread via the thread menu (“Create GitHub issue”). When a thread already has an issue, the menu shows “Go to GitHub issue” instead.