Skip to Content
Documentation

Reactions

Reference

Reactions API reference for VitNode - defineReactionTarget options, the reactions content type option, ReactionBar, routes, limits, live channel and events.

Exact options, routes and limits of VitNode reactions. For a walkthrough, start with Reactions.

reactions on a content type

defineContentType({ reactions }) from @vitnode/api/content takes true, false or an object. It needs publicApi.

NameTypeDefaultDescription
reputationbooleantrue when there is an authorReactions move the author's reputation.

Any other key throws a ContentEngineError. Which reactions exist, who may use them, how many and whether authors may react to their own records are AdminCP settings.

ReactionTargetDefinition

defineReactionTarget(definition) from @vitnode/api/reactions. Register the result in buildApiPlugin({ reactions: { targets } }). Server-only.

NameTypeRequiredDescription
typestringYesStable id stored with every reaction, lowercase and dot-separated, such as forum.topic.
parseId(value: string) => string | nullYesValidates a client-sent id; null rejects it.
access(c, { ids }) => Promise<Map<string, ReactionTargetAccess>>YesFor a batch of ids, as the current visitor: { canRead, authorId, locked? }. Missing ids are unreadable.
preview(c, { ids }) => Promise<Map<string, ReactionTargetPreview>>No{ title, url, label } for timelines. Without it, the target's reactions stay out of timelines.
reputationbooleanNoDefaults to true.

deleteReactions(c, { pluginId, type, ids }) removes every reaction of the given items and takes back their reputation. Content Engine types call it when a record is deleted; a daily cron cleans up records removed by a database cascade.

ReactionBar

ReactionBar from @vitnode/core/tanstack/reactions draws a pill per reaction with its count and a picker. Hovering a pill opens a card with the first five people who gave that reaction and a link to the full list; a pill the viewer can't press opens that list on click.

NameTypeRequiredDefaultDescription
target{ pluginId: string; type: string; id: string }Yes-The item; build it with contentTarget for content.
enabledbooleanNotruefalse skips the read and renders nothing.
classNamestringNo-Classes for the wrapper.

Counts of 1,000 and more are shortened with Short Number. useContentComments takes reactions: id => ContentTarget to draw a bar under every comment.

The same module exports:

ExportUse
ReputationThe colored reputation pill: <Reputation value={n} />. See Reputation.
ReactionIconOne reaction's emoji, icon or image at icon size.
reactionsCatalogQueryOptionsThe catalog and what the viewer's roles allow, for a custom picker.
useReactionsLiveLive counts for a target while an element is on screen, for a custom bar.

Routes

Every route is under /api/@vitnode/core. Call them with fetcher({ plugin: "@vitnode/core", module: "reactions", ... }).

MethodPathDescription
GET/reactions/catalogEnabled reactions with usable and remainingToday for the viewer, plus maxPerItem, live and resetsAt.
GET/reactionsSummaries of up to 100 ids of one pluginId and type: counts, total, viewer, canReact, seq.
PUT/reactionsAdd reaction to { pluginId, type, id }. At a per-item limit of 1, it replaces the previous one.
DELETE/reactionsRemove reaction, or all of the member's reactions on the item without it.
GET/reactions/usersWho reacted, newest first, 50 per page, optionally one reaction.
GET/reactions/reputation/{userId}Reputation and reactions received per reaction.
GET/PUT/reactions/me/settingsThe member's showReactionsOnProfile.
GET/users/{userId}/timelineWhat the member wrote and the reactions they gave, merged, newest first.

AdminCP routes live under /admin/reactions: list, /create, /{id}, /{id}/impact, /reorder, /upload, /recount and /roles/{roleId}. They need reactions:can_view or reactions:can_manage; role settings need roles:can_view or roles:can_edit.

Errors of PUT /reactions

StatuserrorCause
401sign_inA guest.
403reacting_disabledNo role of the member can react.
403reaction_not_allowedNo role of the member may use this reaction.
403self_reaction, lockedThe member's own item while none of their roles allows reacting to own content, or a locked item.
404not_foundUnknown type, bad id, disabled reaction, or an item the member cannot read.
409item_limitThe member reached the per-item limit (2 or more).
429daily_limit, reaction_daily_limitA daily limit is used up; resetsAt is the member's next midnight.

Limits

LimitValue
Reactions in the catalog50
Points per reaction-100 to 100
Reactions per item, per role1 to 50, or unlimited
Uploaded image512 KB, scaled to fit 256x256; PNG, JPEG, WebP, GIF
Targets per summary request100
Live subscriptions per connection200

Live channel

reactionsLiveChannel from @vitnode/api/lib/reactions/live/protocol runs on the shared WebSocket. The browser joins one room per item on screen with { type: "join", clientId, pluginId, targetType, ids }; the server checks access for the whole batch and answers joined with the rooms it refused. Each write sends { type: "counts", room, counts, total, seq }; drop messages with a lower seq than you have. Memberships are checked again every minute, and a deleted item sends revoked. ReactionBar does all of this for you.

Events

EventPayload
reaction.added{ pluginId, targetType, targetId, targetAuthorId, reaction, points, userId }
reaction.removedSame as reaction.added.
reaction.changedSame, plus previousReaction, when a new pick replaced the old one.
reputation.changed{ userId, delta, total, reason: "reaction" | "recount" }
reaction.catalog_changed{ action: "created" | "updated" | "deleted" | "reordered", reactionId }

Import the definitions from @vitnode/api/events/reactions.