provideErrorHandler

In the browser, many failures happen outside any try: an asynchronous on:click handler rejects, onMounted throws, a late-mounted component reloads, a Socket channel drops. provideErrorHandler(handler) registers who receives these failures: the calling component and all its descendants, except those registering their own observer. handler receives the error and its source (ErrorSource), to show an alert, send it to a monitoring service or both.

Without an observer, the failure goes to mountClientApp's onError or, if absent too, the console. It is exported from @meekojs/meeko and auto-imported in framework applications.

Usage#

<!-- app/app.meeko -->
<script lang="ts">
const failure = signal<string | null>(null);
provideErrorHandler((error, source) => {
  failure.value = error instanceof Error ? error.message : String(error);
  console.error(`[${source}]`, error);
});
</script>

<template>
  <p if:when="failure.value" role="alert">Something went wrong: {failure.value}</p>
  <div class="site-root"><MeekoOutlet /></div>
</template>

A rejecting handler on any page leaves the message in the alert, instead of an unhandled rejection.

Type#

function provideErrorHandler(handler: ComponentErrorHandler): void

type ComponentErrorHandler = (error: unknown, source: ErrorSource) => void

type ErrorSource =
  | "event"
  | "effect"
  | "cleanup"
  | "mounted"
  | "navigation"
  | "socket"
  | "uncaught"
  | "rejection"

Parameters#

source tells you where the failure was observed:

Return value#

void. Without an active component it throws Error: provide() requires an active component root, because it provides the observer through provide.

Examples#

An alert per section#

A branch can have its own observer; failures inside no longer propagate to the application's observer.

<!-- app/components/CheckoutPanel.meeko -->
<script lang="ts">
const snippets = defineSnippets<{ default: [] }>();
const problem = signal("");
provideErrorHandler((error) => {
  problem.value = isClientError(error) ? "The server rejected the payment." : "Could not connect. Try again.";
});
</script>

<template>
  <section>
    <p if:when="problem.value" role="alert">{problem.value}</p>
    <render snippet="snippets.default" />
  </section>
</template>

Send to a monitoring service#

// app/composables/report.ts
import type { ComponentErrorHandler } from "@meekojs/meeko";

export const reportError: ComponentErrorHandler = (error, source) => {
  const message = error instanceof Error ? error.message : String(error);
  void fetch("/api/client-errors", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ message, source, path: location.pathname }),
    keepalive: true,
  });
};

<script lang="ts">
provideErrorHandler(reportError);
</script>

A switch on the source#

ErrorSource may gain members in a minor version: a switch needs a default branch.

import type { ErrorSource } from "@meekojs/meeko";

function label(source: ErrorSource): string {
  switch (source) {
    case "navigation": return "Could not open the page";
    case "socket": return "Connection lost";
    default: return "Something went wrong";
  }
}

Common mistakes#

Read error.message without checking its type#

provideErrorHandler((error) => console.log(error.message));

meeko check reports TS18046: 'error' is of type 'unknown': any value can be thrown, not just an Error.

provideErrorHandler((error) => console.log(error instanceof Error ? error.message : String(error)));

Expect it to catch render failures#

The observer receives failures after mounting: events, onMounted, navigation, Socket. An error thrown by the script or template during rendering or hydration fails that render and is shown by the error page.

<script lang="ts">
const props = defineProps<{ items: { name: string }[] }>();
provideErrorHandler(() => { /* not called */ });
const first = props.items[0]!.name; // with an empty list: TypeError during rendering
</script>

Handle potentially missing data in the script; for a page that can fail, use +error.meeko or app/error.meeko:

const first = computed(() => props.items[0]?.name ?? "Sin elementos");

Call it outside a component#

// app/utils/errors.ts, evaluated on import
provideErrorHandler(reportError);

Throws Error: provide() requires an active component root. Call it in a component's script (for the entire application, app/app.meeko), or use mountClientApp's onError in a custom host.

<!-- app/app.meeko -->
<script lang="ts">
provideErrorHandler(reportError);
</script>

Notes#

• Browser only. SSR has no events or mounting: a server render failure responds with the error page and reaches the server observer, not this one.
• Nearest observer. The nearest ancestor's observer wins. A component with no observer in its branch only sends failures to the application's onError or the console, never another branch's observer.
• Expected errors. A ClientError (an expected server response, such as a 409) also reaches here if nobody catches it; useForm handles it itself and only delivers unexpected failures.
• No duplicates. A failure already received by a Meeko observer is not reported again if it escapes to window.
• Security. The error may contain response or user data: do not render it with html, and filter what you send to an external service.

Related#

• onMountedRuns a function once in the browser after the component has hydrated or mounted; never in SSR.
• effectRuns a synchronous function now and whenever a signal it read changes; returns the function that stops it.
• provideProvides a value under a context key in the active component and all its descendants.
• ClientErrorThe error API, RPC and Socket clients use to reject an error response from the server, with its code, status, requestId and per-field issues.
• mountClientAppHydrates server-rendered HTML in the browser and manages client navigation, with history, links, route middleware, data payloads and cleanup.
• ErrorsMeeko as a full-stack framework
• Global browser failuresMeeko as a full-stack framework