---
title: Events overview
description: Publish what happened in your app and let other functions react.
pagination: false
sidebar:
  icon: radio
---

An event records that something happened in your application, such as an order being created. Other functions can subscribe and react—for example, sending a confirmation and recording analytics after an order is created.

The original operation does not wait for these reactions to finish. Use events for follow-up work; use a normal function call when you need the result before continuing.

> **Start here**
>
> Start with [React to order events](/guides/events/react-to-order-events) to install the runtime,
> publish an event, and verify its subscriber. Use [Define an event](/docs/modules/events/define)
> for configuration and the [Events reference](/docs/api/events) for exact contracts.

An event consumer may submit a [task-first job](/docs/modules/jobs/quickstart) when the follow-up needs durable
execution. Publishing an event is not an atomic database write plus task admission.

## Pre-setup

Application events currently use the filesystem provider. It has no Docker recipe; Redis's
cache/realtime adapters do not provide application events. Other configured capabilities
can still use local Docker in this same application.

1. **Install the event provider**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/local@0.7.12
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure event delivery**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Application events use the supported filesystem provider, which has no Docker recipe. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { localEvent } from "@relkit/local";

    export default defineApp({
      env: defineEnv({}),
      event: localEvent(),
      defaults: { event: "default" },
    });
    ```

    This path requires no credentials or new `defineEnv` fields. The `default` profile stores
    state under `.relkit/state`; preserve that directory across restarts. A scaffold may already
    have added this binding—reuse it instead of creating a second profile.

3. **Validate the event and consumer**

    After registering the event and listener, run `bun run check`, `bun run typecheck`, and
    `bun run dev`. Follow [Handle order events](/guides/events/react-to-order-events) to publish
    an event and verify its consumer. Defining an event alone does not run a listener.

## The Events API

| API                                                           | What you use it for                                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`defineEvent`](/docs/api/events#defineevent)                 | Name the event and define the data it carries.                                                                  |
| [`defineFunction`](/docs/api/functions#definefunction)        | Perform an operation, then publish with `context.events[eventId].publish(data)`. List the event in `publishes`. |
| [`defineEventFunction`](/docs/api/events#defineeventfunction) | Subscribe with `event: "orders.created"` and run your handler when it is published.                             |

## See your subscribers

After [installing and binding the event runtime](/guides/events/react-to-order-events#install-and-bind-the-selected-event-runtime),
start the app. If you choose inspection, complete the separate [Inspector setup](/docs/modules/operations/inspector)
and open its UI at `http://localhost:3210`. Select **Events & listeners**, then open an event.
**Publishers** shows which functions send it; **Consumer functions** shows its subscribers.

<img
  src="/inspector-event-subscribers.jpg"
  alt="Inspector showing orders.created, its publisher, and its subscribing functions"
/>

Follow the [order confirmation example](/guides/events/react-to-order-events) to publish and consume an event
in your existing app. Use [Define an event](/docs/modules/events/define) for the descriptor details.