Built-in Events

Every event VitNode and its first-party plugins emit today, grouped by domain. Listen to any of them from your own plugin with buildEventListener - no import from the emitting plugin is needed, because the event map is global.

Quick start

Pick a name from the tables below, write a listener for it, and register the listener on a top-level module's events array:

import { buildEventListener } from '@vitnode/core/api/lib/events'

export const welcomeListener = buildEventListener({
  event: 'user.created', 
  name: 'send-welcome-email',
  handler: async (c, payload) => {
    await c.get('queue').dispatch({
      name: 'send-welcome-email',
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})

Nothing else has to change: the payload type comes from the name, and the delivery guarantees are the same for a core event as for one of your own.

Core events (@vitnode/core)

Six names, all declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts. Every one of them fires after the write it describes has committed.

Content Engine events

Every content type declared with the Content Engine gets its own event names, built from its id: content.<id>.<action>. For the example plugin's example.article that means content.example.article.created, and for the blog's blog.post it means content.blog.post.created.

Which actions exist depends on what the definition opts into. A content type that declares nothing beyond its fields emits three events; one that declares everything emits sixteen.

The gating is in the types, not just at runtime: ContentEventsFor expands to literal keys only for the features the definition enables. The example plugin's example.article declares editorial, so content.example.article.restored type-checks; example.category is one text field and nothing else, so content.example.category.restored is not a key on the map and a listener for it does not compile.

Record events

Translation events

A content type with localization emits one event per translation mutation, in addition to the record events above. Every one of them carries locale and languageId, so a listener never has to go and ask which language moved.

Delivery events

A content type with delivery emits two more when its public URL moves. Both arrive alongside the lifecycle event that moved it - updated, restored, a publication transition or a translation_* - never instead of one: a field moving and a URL moving are different facts with different audiences.

A scheduled event may arrive twice

Announcements for a scheduled transition run in a durable queue task that retries whenever the event, the search write or a cache origin failed - and a retry re-emits an event some listeners already received. Delivery is at-least-once, deliberately: the alternative is a transactional outbox, which the engine does not have.

A listener whose work must happen exactly once keys off scheduleId, which is stable across every attempt at the same booking:

handler: async (c, payload) => {
  if (payload.scheduleId && (await alreadyDone(payload.scheduleId))) return

  await sendTheAnnouncement(payload.contentId)
}

An interactive publish is emitted once, by the route that performed it, and carries no scheduleId.

The envelope's owner is the content type's plugin

pluginId on the envelope answers "whose event is this", not "who was running at the time". Those come apart the moment something happens on a schedule: core owns the queue handler, so c.get('plugin') says @vitnode/core, while content.example.article.published belongs to the example plugin as much as it ever did.

queue task owner    @vitnode/core        ← who runs the handler
event envelope      @vitnode/example     ← who owns the content type

The engine passes the owner explicitly on every emit, so ownership does not depend on which route module or queue handler invoked it. Your own code can do the same when it emits on someone else's behalf:

await c.get('events').emit('blog.post.created', payload, {
  pluginId: '@vitnode/blog', 
})

Omit the option and nothing changes: the envelope falls back to c.get('plugin') and then to @vitnode/core.

Failures are reported, not thrown

emit() reports rather than throws. Listeners run after the write it describes has committed, and a broken listener is not a reason to tell somebody their save failed - so a failure comes back in the result instead, and is written to core_logs twice over: once per listener by the transport (Event listener "plugin:module:listener" for "<event>" failed: ...), and once as a JSON summary behind the greppable [content-effects] prefix by whichever effects helper emitted it - the editorial, translation, delivery and scheduled paths. A plain created/updated/deleted on a content type without editorial goes straight to the transport, so it produces the first line only.

const result = await c.get('events').emit('blog.post.created', payload)

result.delivered // listeners that ran
result.failures // [{ pluginId, module, listener, error }]

Interactive routes ignore that result on purpose, because the mutation succeeded either way. Background work usually should not: the scheduled-effects task inspects failures and retries the whole delivery when it is non-empty.

Blog events (@vitnode/blog)

blog.post.created and blog.post.updated

The adapter reads the article's categories back to fill in categoryId, so a record deleted in between is simply not announced - and so is one with no categories yet.

A listener would push a realtime "new post" notification, ping a webhook (from a queue task) that shares the post to social media, invalidate an external cache, or keep plugin-owned derived data such as related posts in sync.

blog.post.deleted

No categoryId, unlike created and updated: the row is gone by the time this is emitted, so there is nothing left to read it from - and inventing one would put a wrong id into an audit trail. A listener that needs the category should watch content.blog.post.deleted and keep its own index.

A listener would remove the post from an external index or feed.

blog.category.created and blog.category.updated

A listener would keep a navigation menu or an externally-cached category tree in sync, or notify an external CMS of a taxonomy change.

blog.category.deleted

A listener would drop the category from a cached navigation tree. It never has to fan out to the category's posts, because a category with posts cannot be deleted in the first place.

Gotchas

Deliberately not emitted yet

High-frequency or consumer-less events are added only when a listener needs them, so the catalog stays meaningful. There is currently no user.signedIn, user.passwordResetRequested, or file.uploaded. If you need one, open an issue or PR - adding an event is a one-line emit plus an entry in the VitNodeEvents map. (user.deleted is the special case: it is already on the map, and waits on core growing a user-deletion flow.)

Next