What Are the Design and Technical Characteristics of utterances?

Updated

utterances is a lightweight comments widget built on GitHub issues, styled with Primer (the CSS toolkit that powers GitHub) and implemented in vanilla TypeScript. It supports light and dark themes, ships no font downloads, JavaScript frameworks, or polyfills for evergreen browsers, and stores all comment data in GitHub issues rather than a separate database.

How the Widget Works

When utterances loads on a page, it calls the GitHub issue search API to find the issue associated with that page. The match is made by url, pathname, or title, depending on configuration. If no matching issue exists, nothing breaks: the utterances-bot creates the issue automatically the first time someone comments.

To post a comment through the widget, a visitor must authorize the utterances app via GitHub's OAuth flow so the app can post on their behalf. Alternatively, anyone can comment directly on the corresponding GitHub issue.

Design Characteristics

Characteristic Detail
Visual style Styled with Primer, GitHub's own CSS toolkit
Themes Light and dark theme support
Tracking and ads No tracking, no ads
Data ownership No lock-in; all data lives in GitHub issues
Licensing Open source

The Primer styling means the widget visually matches GitHub's interface, which keeps it coherent on developer blogs and documentation sites. The absence of tracking and ads is a stated design property of the project, not an optional setting.

Technical Characteristics

  • Vanilla TypeScript. The widget is written in plain TypeScript with no JavaScript framework dependency.
  • No font downloads. The widget does not fetch web fonts, so it adds no font-related network requests to the host page.
  • No polyfills for evergreen browsers. The project targets modern browsers and does not ship compatibility shims for them.
  • GitHub as the backend. Comments are GitHub issues; there is no separate comment database to host or maintain.
  • Automatic issue creation. The utterances-bot creates the issue on first comment, so page authors do not need to pre-create issues per page.

What This Means in Practice

For a site owner, the practical effect is a small embed that inherits GitHub's look, offers a dark theme, and keeps comment data in a repository you control. For readers, commenting requires a GitHub account and an OAuth authorization step, or commenting on the issue directly on GitHub.

The project lists sites using utterances including Haxe documentation and cookbook, sadsloth.net, and danyow.net. If you use it, the project asks that you add the utterances topic to your repo.