Define an event

Name an event and choose the data it carries.

Define an event to give an application fact a stable name and a validated payload.

Pre-setup

Complete event provider setup to install @relkit/local and configure event plus defaults.event in defineApp. No additional defineEnv values are required. This provider has no Docker recipe; retain its .relkit/state data across restarts.

Scaffold an event contract

From an application’s root, with an existing orders service:

bun run relkit add event order-created --service orders

Creates src/services/orders/events/order-created.event.ts, a version-1 contract with a string value payload and ID orders.order-created-event. It registers the event’s type and exposes the event through the service. Pass --internal to omit service exposure.

Use --profile events to select that compatible event profile. Without one, scaffolding reuses a configured default or unique profile, or adds a file-backed localEvent() profile. The sample payload is a starting point; it is different from the hand-authored example below. Declare publication on a function and add a consumer when needed.

For every event scaffolding flag, see the event command reference.

The scaffold normally installs/configures its selected runtime. With --no-install, finish bun install and bun run check. For manual source setup, complete the local event installation and binding before using the descriptor below; its declaration alone does not select a provider.

Define the event

Use defineEvent to name an event and describe its data. In your app, create src/services/orders/events/order-created.event.ts:

import { defineEvent } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const orderCreated = defineEvent({
  id: "orders.created",
  version: 1,
  input: z.object({
    orderId: z.string().min(1),
    sku: z.string().min(1),
    totalCents: z.number().int().nonnegative(),
  }),
});

export default orderCreated;

• id uniquely names the event. Use this same name when publishing and consuming it.
• input describes the data to send with the event.
• version is optional and defaults to 1.

Here, each order event carries an order ID, product code, and total.

Check your event

After adding the file, run this from your app’s root:

bun run check