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.

Event index

• 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
• cron:scheduled — a scheduled job was registered (its runs surface through queue:* on the job name)
• email:sent, email:error — transactional email delivery
• server:start, server:stop — server lifecycle
• warmup:start, warmup:complete — route warmup batch (only with warmup: true)
• error — a page/api/action handler threw
• action:invoke, action:complete — form action lifecycle
• compile:start, compile:complete, compile:error — Svelte SSR build
• recompile:start, recompile:complete — dev rebuild cycle
• recompile:module-churn — entry re-imported many times in a dev session (resource-leak warning)
• client-bundle:complete — hydratable client bundle finished
• island:error — an island errored
• captcha:verify — a <MochiCaptcha> submission was verified or rejected
• file:change — dev-only file watcher
• image:store, image:delete — <Image> cache activity
• image:cache-sweep — aggregate counts per janitor sweep (see Images)
• cache:read, cache:revalidate — see Cache events
• memory:pressure — the OS reported low memory; fires before the cache drain so other subsystems can reclaim too (see Cache)
• cache:pressure — the OS reported low memory and in-memory caches were drained (see Cache)

Subscribing

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 never pile up duplicate listeners.

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

Namespace name (metrics:request, not request) so unrelated subsystems do not 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 same id is on the request context.

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

Event reference

Each event ships a typed payload matching MochiEventMap in events.ts.

request

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

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.

sse:message

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

sse:close

Fires when the SSE stream closes. A client disconnect or an explicit close both count.

queue:added

Since: 0.10.0 (not released yet): The bulk field is new in 0.10.0.

Fires after queue.add() / queue.addBulk() enqueues a job. See Queues.

queue:addedBulk

Since: 0.10.0 (not released yet): queue:addedBulk is new in 0.10.0.

Fires once per addBulk() call that inserted at least one job, alongside the per-job queue:added events. The console logger prints this summary instead of the per-job lines.

queue:active

Fires when a worker starts a job.

queue:completed

Fires when a job’s processor returns successfully.

queue:failed

Fires when a job’s processor throws. One emission per failed attempt.

queue:error

Fires for a queue-runtime error not tied to one job, for example a poll failure.

email:sent

Fires after Mochi.email() hands a message to its transport. The email:message filter can veto it first. 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

Since: 0.10.0 (not released yet): The 'stop' reason is new in 0.10.0 — earlier versions emit this event only on signals.

Fires when the server shuts down — on SIGTERM / SIGINT, or a programmatic Mochi.stop() — after the mochi:shutdown hook runs.

warmup:start

Fires once when the route warmup batch begins. Only emitted with warmup: true.

warmup:complete

Fires once after the route warmup batch finishes. Only emitted with warmup: true.

error

Fires when a page, API, or form action handler throws and the framework returns an error response.

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 through requestId.

action:complete

Fires after a form action returns or throws. One emission per invocation, whatever the outcome.

compile:start

Fires before each Svelte SSR compile. A cache hit skips it.

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. It 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 finishes and clients are told to reload.

clientBundleCount counts buildClientBundle() calls inside the cycle. For a typical 'file' trigger it must be 1, or 0 when no hydratables are registered. A value above 1 means the registry’s bundle deferral stopped working and you regressed to per-page bundling.

recompile:module-churn

Fires once per dev session, when the entry has been re-imported reloadCount times (default 10). Each reload re-evaluates the whole first-party module graph, so a module-scoped resource is re-created and the old one orphaned — see route-handler HMR. consoleLogger() renders it as a warn-level HMR line; suppress that line with a consoleLogger:line filter matching source.name === 'recompile:module-churn'.

import { mochiEvents } from 'mochi-framework';

mochiEvents.on('recompile:module-churn', ({ reloadCount }) => {
  console.warn(`entry re-imported ${reloadCount}× — hold resources with pinGlobal()`);
});

client-bundle:complete

Fires whenever the registry rebuilds the hydratable client bundle. 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. The client gets one generic message, but this event carries the real cause.

island:error

Fires when an island fails: a server-island render, a hydratable SSR render, or client-side hydration. The framework still ships an error placeholder. See Error boundaries.

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, or a ThumbHash blur placeholder. Emitted once per regeneration, because concurrent misses coalesce. Use it to mirror cache writes to durable storage such as S3.

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. The janitor sweep evicts it, a newer generation supersedes it, or you invalidate it explicitly. Pair it with image:store to keep an S3 mirror in sync. A 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}` });
});

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

consoleLogger() 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.