Crash reports

"use client";

import { reportError, useCanReportError } from "@mediansh/widget";
import { useState } from "react";

export default function ErrorScreen({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const canReport = useCanReportError();
  const [note, setNote] = useState<string | null>(null);

  async function report() {
    const outcome = await reportError(error);
    setNote(outcome.reported ? "Reported." : outcome.reason);
  }

  return (
    <div>
      <p>Something went wrong.</p>
      <button onClick={reset}>Try again</button>
      {canReport && note === null && (
        <button onClick={report}>Report error</button>
      )}
      {note && <p>{note}</p>}
    </div>
  );
}

reportError files the error as a bug in Signal, with the page and a screenshot. With diagnostics on, the browser's recent errors come too. It never throws. medianSupport.reportError and useMedianSupport().reportError are the same function.

Requirements

• A key. MedianSupport, MedianSupportModal, MedianFeedback, MedianContactForm and useMedianContact each record their key as they mount. reportError uses the last one recorded on this page load. Pass apiKey when none has mounted.
• Track bugs and suggestions turned on under Agent → Behavior. With it off, nothing is filed.
• A browser. On the server it returns a reason and sends nothing.

The key is held in memory, so it outlives an error boundary that replaced the tree the widget was in. A full page load forgets it.

In global-error.tsx, pass apiKey. A crash on the first page load can happen before any widget mounts.

const outcome = await reportError(error, {
  apiKey: process.env.NEXT_PUBLIC_MEDIAN_PUBLIC_KEY,
});

NEXT_PUBLIC_MEDIAN_PUBLIC_KEY holds the median_pk_ id from publicKeyFromMedianKey(MEDIAN_KEY). The id is safe in client code.

Options

Limits for state and attach are on Context and diagnostics.

Outcome

type MedianErrorReportOutcome =
  | { reported: true; joined: boolean }
  | { reported: false; reason: string };

joined is true when the report joined a bug that was already filed.

A report that does not land puts queued attach() entries back, together with the entries from the attach option. A second press carries them, and so does the next message, note or contact form send.

What lands on the report

• The title leaves out the error's name when it is Error or Exception, or when the message already starts with it.
• The message is cut at 300 characters. An error with no message is Unnamed error.
• Stacks are cut at 4,000 characters. The name and the digest are cut at 60.
• Route, Digest and state come first among the 20 app state entries, so a full appState loses its last entries rather than the crash's.
• The report is filed at once. No model reads it first.
• A new bug is then checked against the list like any other, may be merged into a matching one, and goes to your connected issue tracker. See Signal.

Joining

• A report joins a bug with the same title, unless that bug was declined. Case and punctuation are ignored. Only the 60 most recent bugs that were not declined are compared.
• The same error on the same route gives the same title, so many people hitting one crash make one bug with one reporter row each.
• A visitor who reports the same crash again updates their row.

useCanReportError

const canReport = useCanReportError();

• It turns true by itself when a component mounts. You do not need to re-render.
• It does not check Track bugs and suggestions. A press can still return the unavailable reason.
• It ignores the apiKey option. If you always pass apiKey, show the button without it.

Crash reports share the widget's rate limit for sends. See Conversations.