Custom adapter

By default, c.get("events").emit() runs the matching listeners inside the emitting request, on that instance only. An events adapter decides what emit() does instead. This guide builds a hybrid adapter. It runs VitNode's listeners exactly as before, then appends each event to a Redis stream that other services can read.

Before you beginCopy Anchor Link

• A Redis server, and the redis package (node-redis) in the API app's dependencies.
• The API config of your app, src/vitnode.api.config.ts.

import type { EventsApiPlugin } from "@vitnode/core/api/models/events";

import { LocalEventsAdapter } from "@vitnode/core/api/adapters/events/local";
import { createClient } from "redis";

const redis = createClient({ url: process.env.REDIS_URL });

// node-redis throws "error" events as uncaught exceptions without a listener.
redis.on("error", () => {});
void redis.connect().catch(() => {});

const local = LocalEventsAdapter();

export const RedisStreamEventsAdapter = (): EventsApiPlugin => ({
  name: "redis-stream",

  publish: async (c, envelope) => {
    // VitNode's own listeners, unchanged: in this request, one after another.
    const result = await local.publish(c, envelope);

    try {
      await redis.xAdd("vitnode:events", "*", { event: JSON.stringify(envelope) });
    } catch (err) {
      const error = err instanceof Error ? err.message : String(err);

      await c.get("log").error(`Forwarding "${envelope.name}" to Redis failed: ${error}`);
      result.failures.push({
        error,
        listener: "redis-stream",
        module: "adapter",
        pluginId: envelope.pluginId,
      });
    }

    return result;
  },
});

import { buildApiConfig } from "@vitnode/core/vitnode.config";

import { RedisStreamEventsAdapter } from "./lib/events/redis-stream-adapter";

export const vitNodeApiConfig = buildApiConfig({
  // ...plugins, metadata and the rest of your config
  events: {
    adapter: RedisStreamEventsAdapter(), 
  },
});

Check the resultCopy Anchor Link

Restart the API and trigger an event, such as creating a note in the Events guide. The listener's log line appears as before, and the stream holds the event:

redis-cli XRANGE vitnode:events - +

Each entry has one field, event, holding the JSON envelope.

Reading the stream elsewhereCopy Anchor Link

Whatever reads vitnode:events, with XREAD or a consumer group, runs its own code: a search indexer, an analytics pipeline, another app. It does not run VitNode listeners and has no Hono context. Work that must happen reliably inside VitNode, with retries, belongs in a queue task a listener dispatches.

The interfaceCopy Anchor Link

import type { EventEnvelope, EventEmitResult } from "@vitnode/core/api/models/events";
import type { Context } from "hono";

interface EventsApiPlugin {
  /** Shown in logs and returned by c.get("events").name(). */
  name: string;
  publish: (c: Context, envelope: EventEnvelope) => Promise<EventEmitResult>;
}

emit() catches an adapter that throws, logs it, and reports it as one failure with module: "adapter". To run listeners yourself, read them from c.get("core").events.listeners, as LocalEventsAdapter does.

RelatedCopy Anchor Link

• Events: emit and listen, and how listeners run.
• Built-in events: every event core and the Content Engine emit.