Consume an event

Run your code when an event is published.

An event function reacts to a published event without returning a result to the publisher.

Scaffold an event-only function

First complete event runtime installation and binding. The scaffold reuses or selects a profile; a manually copied subscriber does not install a provider.

After defining the orders.created event, run from the application root:

bun run relkit add event-function on-order-created --service orders \
  --event orders.created --delivery durable

Creates src/services/orders/functions/on-order-created.function.ts. --event selects an existing event by ID, binding, or filename. The default delivery is durable; choose transient for non-durable delivery. --profile selects a compatible event provider profile. In a terminal, omitted choices are prompted; headless execution needs an unambiguous event target.

The function is event-only, not a public callable service member. Review the placeholder handler against your event payload before implementing its reaction; the CLI does not generate business logic.

If you scaffolded the event with add event order-created, use its generated ID orders.order-created-event for --event instead. Keep the subscriber’s selected event ID when adapting the handler below. For manual setup, create the subscriber directly.

For every subscriber scaffolding flag, see the event-function command reference.

Create a subscriber

Use defineEventFunction to run work when an event is published. After defining orders.created, create src/services/orders/functions/order-confirmation.function.ts:

import { defineEventFunction } from "@relkit/app/events";

const orderConfirmation = defineEventFunction({
  id: "orders.confirmation",
  event: "orders.created",
  handler: async (order, context) => {
    context.log.info("order.confirmation.requested", { orderId: order.orderId });
  },
});

export default orderConfirmation;

• id uniquely names this function.
• event is the exact ID of the event to consume.
• handler receives the event data. This example logs a confirmation; replace the log with your own work, such as sending an email.

Run bun run check from your app’s root. RELKIT runs the handler when orders.created is published; you do not call it yourself.

Use defineFunction when the caller needs a result, such as the created order. Use defineEventFunction for a reaction that runs separately, without returning a result to the publisher.

When the reaction must survive the consumer process or expose run progress, trigger a task-first job from the event function. Event delivery and task admission remain separate operations; use an explicit stable idempotency key where repeated event delivery could duplicate business work.

Add another subscriber

To run multiple reactions, add another event function with a different id and the same event.