Comments Module Recipe

The Comments module puts a discussion on any record — a ticket, a document, an order, a page. It shows the comments as threads, lets people answer any comment at any depth, and lets them react with an emoji.

• Threads. Every comment has a Reply button, not only the top one. Each level is indented a little less than the one before (41 px for the first, 22 px for each deeper one), so a long thread stays on screen.
• A comment box with bold, italic, underline, bulleted lists and an emoji picker. Ctrl Enter (⌘ Enter on macOS) sends, Esc cancels a reply, and Enter inside a bullet starts the next one.
• @Mentions. Type @ and a name: people are searched after a short pause, ↑ ↓ move, Enter or Tab chooses, Esc closes the list. A mention is stored in the text as @[Name](user:<uuid>) and shown as a chip; a mention of you stands out.
• Pictures. A picture button, and paste from the clipboard (a screenshot works). PNG, JPEG, GIF or WebP up to 10 MB, at most 20 per comment, shown as thumbnails that open a viewer with previous, next and ← →. A picture alone is a valid comment. They are uploaded to the Files API and stored as file ids in photos.
• Reactions. Twelve fixed emoji, one chip per emoji in use with its count, highlighted when it is yours, with the names in the tooltip. They change at once and roll back if the server refuses.
• No blank screen. Posting, replying and reacting never clear the list. It stays on screen and is replaced quietly when the server has answered.
• Safe text. A comment is drawn as React nodes only. Anything that is not one of the marks stays plain text, so a comment cannot inject markup.

The pieces

Install

buildpad add comments

Mount it

'use client';
 
import { useMemo } from 'react';
import { CommentsKit, itemsAdapter } from '@/components/ui/comments';
 
export function TicketComments({ ticketId, user }: { ticketId: string; user: { id: string; name: string } }) {
  const adapter = useMemo(
    () =>
      itemsAdapter({
        collection: 'ticket_comments',
        reactionsCollection: 'ticket_comment_reactions',
        hostField: 'ticket',
        hostId: ticketId,
        meId: user.id,
        linkFor: (commentId) => `${location.origin}/tickets/${ticketId}?comment=${commentId}`,
      }),
    [ticketId, user.id]
  );
 
  return <CommentsKit adapter={adapter} meId={user.id} meName={user.name} />;
}

Keep the adapter stable (useMemo): the kit reloads when it gets a different one, which is how it switches to another record. itemsAdapter calls apiRequest, so it works whether the app talks to DaaS through its own /api/items/... routes or directly, as DaaSProvider is set up.

What the adapter decides

A method an adapter leaves out switches that feature off:

Comments are immutable by default: a correction is a new reply.

Props of CommentsKit

Other column names

itemsAdapter defaults to the names of the add-comments skill. Map your own with fields:

itemsAdapter({
  // …
  fields: {
    parent: 'reply_to',
    createdAt: 'made_at',
    reaction: { reactedBy: 'user_id' },
  },
});

Mentions: what the server must do

The browser only writes the token. Who may be mentioned is the server’s job: the create hook of the add-comments skill rewrites the token of anyone who may not read the record into plain @Name, so a forged id notifies nobody. The picker searches /api/users (active users), so it can offer people who cannot read the record; pass your own mentions function to narrow it. At most 10 distinct people become mentions in one comment; the rest stay plain text. The text is the source of truth: there is no separate mentions column. A name inside a token is the name on the day it was written.

Pictures: what to know

• Where they go. itemsAdapter({ images: true }) posts each picture to POST /api/files as multipart (the same route the files module uses) and keeps the returned file id. The comment stores the ids in photos; the thumbnails and the viewer load /api/assets/<id>, resized for the thumbnail.
• What is accepted. The browser checks the type (PNG, JPEG, GIF, WebP; SVG is refused, because it can carry script), 10 MB and 20 pictures, and says why when it refuses one. A refused picture does not stop the others in the same choice. Send waits while a picture is still uploading.
• The server must check too. The create hook bounds photos (a list of at most 20 strings), as in step 3 of the add-comments skill. The browser checks are for the person typing, not for security.
• Who can see a picture is decided by the Files permissions of the viewer, not by who may read the comment. Anyone who may read that file can open it by its id.
• Deleting a comment does not delete its pictures. The files stay in the library; clean them up with your own job if that matters.
• Editing changes the text only. Pictures cannot be added to or taken off a posted comment.

Notification emails

Emails are sent by the DaaS, not by the browser. The package ships three small files in its schema/ folder (and in the npm package): a custom service, services/comment_mail.js, and two action hooks, hooks/notify-on-mention.hook.js and hooks/notify-on-reply.hook.js. They are pasted into your DaaS; buildpad add comments does not copy them. The folder’s README.md has the install steps; in short: edit CONFIG at the top of the service, expose APP_URL to services (RUNTIME_ENV_WHITELIST_CUSTOM_SERVICE), create the service, then the two hooks on <your comment collection>.items.create, with SMTP configured.

• Never the author themself, and never twice for one comment. A person a reply already mentions gets the mention email only. The hooks fire once, on create: editing a comment emails nobody.
• Skipped, not failed: people who are not active, who have no email, or whose address cannot receive mail (.test, example.com, daas.internal, a service account).
• The comment is never affected. The hooks run after the write and catch every error. A mail server that is down loses the email, not the comment. Failures are written to the DaaS log (/logs); a failed email is not retried, and there is no record of what was sent.
• Safe HTML. Every value in the email card is escaped; the text part is plain text.
• Nothing is sent until you say who may be emailed. As shipped, the service fails closed and logs why. Set CONFIG.mentionsCheckedByCreateHook: true when your create hook already turns the mention of anyone who may not read the record into plain text, or fill in CONFIG.canRead with your own access rule.
• The commenter’s address stays private. Emails have no Reply-To unless you set CONFIG.replyToAuthor: true, which shows the commenter’s address to everyone emailed.
• Everyone is emailed at once. Mentions are sent in parallel, so a slow mail server cannot run out the service’s time limit partway down the list.

How it loads

A whole thread is read in two requests however deep it is: the top-level comments, then every reply whose root is one of them (in groups of 40 ids), with the reactions and the authors nested. A reply whose parent is not loaded stays at the top and says so. Replies deeper than 40 levels are not drawn.

Strings

Every word comes from the comments namespace of the shared dictionary, in English and Bahasa Indonesia. Override them with BuildpadI18nProvider or the translations prop.

Not in this version

• An unread marker for mentions and a Mentioned page. The mention itself is stored, shown as a chip, and emailed (see above), but nothing tracks whether it was read.
• A record of the emails sent, or a retry of a failed one.
• Guests on a public link, and highlight or pin anchors on a document.