Events

Mochi exposes a process-wide mitt emitter named mochiEvents. Subscribe from application code to feed metrics, audit logs, custom log destinations, or anything else that needs a structured view of server activity.

Event names use a namespace:action convention. Every key is in the typed MochiEventMap, so handlers receive a precise payload type without casts.

mochiEvents.on

• request — every HTTP request (page or API)
• ws:open, ws:message, ws:close — WebSocket lifecycle
• sse:open, sse:message, sse:close — Server-Sent Events lifecycle
• queue:added, queue:active, queue:completed, queue:failed, queue:error — background job lifecycle
• email:sent, email:error — transactional email delivery
• server:start, server:stop — server lifecycle
• warmup:start, warmup:complete — route warmup batch lifecycle (only with warmup: true)
• error — page/api/action handler threw, response was an error page or apiError
• action:invoke, action:complete — form action lifecycle
• compile:start, compile:complete, compile:error — Svelte SSR build
• recompile:start, recompile:complete — dev rebuild cycle (one per save)
• client-bundle:complete — hydratable client bundle finished
• island:error — a hydratable, server, or client-hydrate island errored
• captcha:verify — a <MochiCaptcha> submission was verified or rejected
• file:change — dev-only file watcher
• image:store, image:delete — <Image> cache file written / removed
• image:cache-sweep — aggregate counts per janitor sweep (see Images)
• cache:read, cache:revalidate — see Subscribing to cache events

Subscribing

Two patterns:

import { mochiEvents } from 'mochi-framework';

mochiEvents.on('request', ({ method, path, status, duration }) => {
  metrics.timing('http.request', duration, { method, path, status });
});

mochiEvents.setHandler

Use setHandler(name, type, handler) to register a named subscriber. It replaces any prior handler stored under the same name, so dev re-imports of the same module never pile up duplicate listeners.

import { mochiEvents } from 'mochi-framework';

mochiEvents.setHandler('metrics:request', 'request', ({ status, duration }) => {
  metrics.timing('http.request', duration, { status });
});

Namespace name (metrics:request, not request) so unrelated subsystems do not silently evict each other.

hasSubscribers

Use hasSubscribers(name) to skip payload construction when nobody is listening:

import { hasSubscribers, mochiEvents } from 'mochi-framework';

if (hasSubscribers('compile:error')) {
  mochiEvents.emit('compile:error', expensivePayload());
}

requestId correlation

Every HTTP request carries a stable requestId on request, error, action:invoke, and action:complete. Use it to stitch a 500 trace together (the error payload + the matching request payload). The same id is on the request context:

import { getRequestContext } from 'mochi-framework';

const { requestId } = getRequestContext();

To honour an upstream id from a trusted reverse proxy, set proxy.requestIdHeader on Mochi.serve():

Mochi.serve({
  proxy: { requestIdHeader: 'X-Request-Id' },
  // …
});

Event reference

Each event ships a typed payload. The fields below match MochiEventMap in events.ts.

request

Fires once per HTTP response, including CSRF rejects. Covers both Mochi.page and Mochi.api routes.

mochiEvents.on('request', ({ kind, method, path, status, duration }) => {
  if (status >= 500) alerts.fire({ kind, method, path, status, duration });
});

ws:open

Fires after a successful WebSocket upgrade.

ws:message

Fires for every inbound WebSocket frame, after the user message handler returns.

ws:close

Fires when a WebSocket connection closes.

sse:open

Fires when an SSE stream starts (the ReadableStream is pulled by the runtime).

sse:message

Fires per stream.send() inside an SSE handler.

sse:close

Fires when the SSE stream closes (client disconnect or explicit close).

queue:added

Fires after a job is enqueued via queue.add() / queue.addBulk(). See Queues.

queue:active

Fires when a worker starts processing a job.

queue:completed

Fires when a job’s processor returns successfully.

queue:failed

Fires when a job’s processor throws (once per failed attempt).

queue:error

Fires for a worker-level error not tied to a specific job (e.g. a poll failure).

email:sent

Fires after Mochi.email() hands a message to its transport (or when the email:message filter vetoes it). See Email.

email:error

Fires when a transport throws while sending. Mochi.email() re-throws after emitting.

server:start

Fires once after Bun.serve() binds the listening socket.

server:stop

Fires when the server is shutting down via SIGTERM/SIGINT, after the mochi:shutdown hook has run.

warmup:start

Fires once when the route warmup batch begins, right after the server starts listening. Only emitted when warmup: true is set on Mochi.serve().

warmup:complete

Fires once after the route warmup batch finishes. Only emitted when warmup: true is set on Mochi.serve().

error

Fires when a page, API, or form action handler throws and the framework returns an error response. Useful for routing exceptions to Sentry/Rollbar/Datadog without monkey-patching.

mochiEvents.on('error', ({ kind, path, status, message, stack }) => {
  Sentry.captureException(new Error(message), { tags: { kind, path, status }, contexts: { stack } });
});

action:invoke

Fires immediately before a form action handler runs. Pairs with action:complete via requestId.

action:complete

Fires after a form action returns (or throws). One emission per invocation, regardless of outcome.

compile:start

Fires before each Svelte SSR compile (skipped on cache hit).

compile:complete

Fires after a successful compile.

compile:error

Fires when Bun.build rejects a Svelte source. The framework still throws after emitting; the event exists for tooling that wants the structured logs.

recompile:start

Fires from the dev watcher before a rebuild cycle begins. Production builds never emit. Wraps either a full SSR rebuild (trigger: 'file' | 'svelte-config') or the CSS-only fast path (trigger: 'css').

recompile:complete

Fires after the matching recompile:start, once the rebuild has finished and clients have been notified to reload.

clientBundleCount is the count of buildClientBundle() calls inside the cycle — for the typical 'file' trigger it should be 1 (or 0 if no hydratables are registered). A value > 1 means the registry’s bundle deferral isn’t kicking in and you’ve regressed to per-page bundling.

mochiEvents.on('recompile:complete', ({ trigger, pageCount, clientBundleCount, durationMs }) => {
  logger.info(`HMR ${trigger} pages=${pageCount} bundles=${clientBundleCount} ${durationMs.toFixed(0)}ms`);
});

client-bundle:complete

Fires whenever the registry rebuilds the hydratable client bundle (one Bun.build over HydratableIsland.ts plus a per-component virtual entrypoint). Production builds emit once at startup; dev mode emits during recompileAll() and on lazy first-hit compiles for server islands.

captcha:verify

Fires when verifyCaptcha() finishes, pass or fail. verifyCaptcha() deliberately returns one generic message to the client so a bot can’t tell the failure modes apart — this event is where the real cause stays visible, which makes it the hook for spam dashboards and alerting on a spike of rejections.

mochiEvents.on('captcha:verify', ({ ok, reason }) => {
  if (!ok) {
    metrics.increment('captcha.rejected', { reason });
  }
});

island:error

Fires when an island fails — server-island render, hydratable SSR render, or client-side hydration. The framework still ships an error placeholder; this event lets you observe it.

file:change

Fires from the dev file watcher (chokidar). Production builds do not run the watcher, so this event never emits there.

image:store

Fires when the <Image> cache commits a file to disk: a downloaded full-size original, a resized variant/thumbnail, or a ThumbHash blur placeholder. Emitted once per regeneration (concurrent misses coalesce), so it’s the hook for mirroring cache writes to durable storage like S3.

Read the file synchronously at the top of the handler — it provably exists at emit time — then offload the upload to a fire-and-forget task. A lazy await readFile(path) inside a slow handler could race the janitor sweep and miss the file.

import { readFileSync } from 'node:fs';
import { mochiEvents } from 'mochi-framework';

mochiEvents.on('image:store', ({ kind, src, path, contentType }) => {
  const body = readFileSync(path); // sync: the file is guaranteed present now
  void s3.putObject({ Bucket, Key: `img/${kind}/${src}`, Body: body, ContentType: contentType });
});

image:delete

Fires when the <Image> cache removes a file from disk — evicted by the janitor sweep, superseded by a newer generation, or explicitly invalidated. Pair it with image:store to keep an S3 mirror in sync. Bulk invalidateSrc() only emits per-file deletes while a subscriber is registered.

mochiEvents.on('image:delete', ({ kind, src, path }) => {
  void s3.deleteObject({ Bucket, Key: `img/${kind}/${src}` });
});

cache:read, cache:revalidate

Emitted by MochiCache — see Subscribing to cache events for payloads and a worked subscriber.

Custom events

mochiEvents is a plain mitt emitter — emit your own keys on it for quick experiments. Custom keys are absent from MochiEventMap, so handlers and emit sites lose typing.

Built-in subscribers

logger() (see logger) already prints request, ws:*, sse:*, server:*, error, and cache:revalidate lines. Pass { cache: 'verbose' } to also print every cache:read, or { cache: false } to silence cache logging entirely.