Quickstart

1. Create a project

In the dashboard, create a project and copy its public key (pk_live_…).

The public key is embedded in your page source and is not a secret. It identifies the project; the browser’s Origin header is what authorises the request. A key on its own is useless from an origin you haven’t registered.

2. Register your preview origins

Preview deployments land on hostnames nobody can predict, so Gutternote matches the request origin against patterns rather than a fixed list.

Vercel names previews <project>-git-<branch>-<team>.vercel.app — everything that varies sits inside a single DNS label. So the pattern you want scopes to your team suffix:

https://*-acme.vercel.app     ✅ matches gutternote-git-fix-nav-acme.vercel.app
https://*.vercel.app          ⚠️  matches every Vercel site on the internet

A * globs within one label and never crosses a dot, so https://*-acme.vercel.app can’t be widened into somebody else’s domain. Add your production origin too:

https://acme.com
https://*.acme.com
https://*-acme.vercel.app
http://localhost:3000

3. Add the widget

<script
  src="https://cdn.gutternote.com/v1/widget.js"
  data-gutternote-key="pk_live_..."
  defer
></script>

Gate it to previews so it never ships to production:

app/layout.tsx

{process.env.VERCEL_ENV === 'preview' && (
  <script
    src="https://cdn.gutternote.com/v1/widget.js"
    data-gutternote-key={process.env.NEXT_PUBLIC_GUTTERNOTE_KEY}
    defer
  />
)}

4. Tell Gutternote which build this is

The widget can’t read Vercel’s build environment from the browser, so pass the git metadata through as meta tags. Without this, comments still work but aren’t tied to a branch or PR:

<meta name="gutternote:branch" content={process.env.VERCEL_GIT_COMMIT_REF} />
<meta name="gutternote:commit" content={process.env.VERCEL_GIT_COMMIT_SHA} />
<meta name="gutternote:pr" content={process.env.VERCEL_GIT_PULL_REQUEST_ID} />

5. Comment

Open a preview, hit Comment, and click any element. That’s a thread.

Next: decide where those comment bodies should live.