Comments API

@vitnode/core/tanstack/comments turns a Content Engine content type with thread into a comment section. useContentComments holds the thread's state and actions, and the components render them. For a guided setup, follow Comments, Comment actions and Replies.

Everything here is browser code. It calls the Content Engine's own routes for the thread, permissions, writes, deletes, hiding and reports, and those routes decide every permission.

useContentCommentsCopy Anchor Link

import { useContentComments } from '@vitnode/core/tanstack/comments'

const comments = useContentComments({ queryKey, thread, ...actions })

OptionsCopy Anchor Link

Callback contractCopy Anchor Link

• Write each fetcher call inline and return its response unchanged. The plugin, module, path, arguments and answer then stay typed from your routes; the hook infers the comment id type (number, or string for a uuid type) from thread.
• Don't check the status yourself. The hook reads ok and status: a 2xx is a success, anything else is reported by the section, and a thrown error counts as a failed request.
• An action you leave out never shows. One you wire up still shows only where the server's can* answer allows it.

ControllerCopy Anchor Link

useContentComments returns the controller every component reads. The fields you are most likely to use in a custom layout:

Thread entriesCopy Anchor Link

Each entry of tree and items is a ContentCommentNode:

buildContentCommentTree(items) and countContentCommentReplies(node) are exported for layouts that work on the flat list.

contentCommentsQueryOptionsCopy Anchor Link

The thread's infinite query, for warming the first page in a route's loader. It takes the same queryKey, thread, pageSize and record as the hook and reads the same cache entry:

await context.queryClient
  .infiniteQuery(contentCommentsQueryOptions({ queryKey, thread }))
  .catch(() => null)

Its queryFn throws when the thread route answers anything but 2xx.

ContentCommentsCopy Anchor Link

The complete section: the count, the thread, Load more comments, the composer or a sign-in link, the actions menu, the delete confirmation and the report dialog. It scrolls to and rings the comment a #comment-... link points to, loading more pages until it appears.

<ContentComments comments={comments} />

The section's element id is comments, so #comments links scroll to it. Its messages live in the core.comments namespace; add it to the page's route messages to load them with the page.

Your own layoutCopy Anchor Link

ContentCommentsRoot provides the controller to the building blocks below and renders the dialogs they open. It adds the comment messages to the page's, so your own components inside keep their translations.

import {
  ContentCommentActions,
  ContentCommentComposer,
  ContentCommentsComposer,
  ContentCommentsLoadMore,
  ContentCommentsRoot,
  useContentCommentItem,
} from '@vitnode/core/tanstack/comments'

const MyComment = ({ node }) => {
  const item = useContentCommentItem(node)

  if (item.editing) {
    return (
      <ContentCommentComposer
        editable={item.editing}
        id={node.id}
        label="Edit your comment"
        mode="edit"
        onCancel={item.stopEditing}
        onDone={item.stopEditing}
      />
    )
  }

  return (
    <article>
      {/* your own rendering of node.record */}
      <ContentCommentActions item={item} node={node} />
    </article>
  )
}

;<ContentCommentsRoot comments={comments}>
  {comments.tree.map((node) => (
    <MyComment key={node.id} node={node} />
  ))}
  <ContentCommentsLoadMore />
  <ContentCommentsComposer />
</ContentCommentsRoot>

The Blog plugin's plugins/blog/src/pages/post-comments.tsx is a complete custom layout: rail connectors, collapsible branches, share buttons and slug permalinks, with every action from these components.

Outcomes and errorsCopy Anchor Link

• Writes. The composer posts through useContentPublicWrite: a refused write keeps the text and shows the reason, and with editorial a stale edit shows the version-conflict alert. A success reads the answer's status and approval: Comment posted only when it is public, saved as a draft or waiting for a moderator otherwise.
• Actions. Delete, hide and unhide show Comment deleted, Comment hidden or Comment visible again after the server accepts them. When it refuses, the section shows one message for the cause: signed out, not allowed, gone, busy or unknown.
• Loading. A failed first load shows Try again; a failed Load more keeps the loaded comments and says it failed. A failed background refresh keeps them too; ContentCommentsLiveStatus offers Try again.

GET /thread/branchesCopy Anchor Link

Every content type with thread also gets GET /{publicApi.path}/thread/branches. It re-reads a few top-level comments already on screen, each with every reply below it, using the same root check, visibility, placeholders, depth and truncation as /thread. useContentComments calls it through branches.

GET /api/newsroom/content/article-comments/thread/branches?root=1&ids=4,9

gone means this reader no longer sees the branch: deleted, hidden or unpublished with no visible reply left, not a top-level comment, or under another root. An unreadable root answers 404, as on /thread; more than 10 or malformed ids answer 400.

Guests and readers who can't see hidden comments get the same answer, served from the public read cache with Cache-Control: no-cache. Readers who may see hidden comments, and readers of a hidden root, get a private, no-store answer.

RelatedCopy Anchor Link

• Comments: the guided setup.
• Permissions API: useContentPermissions, which the hook uses for permissionsOf.
• thread reference: the thread option on the content type.