@beignet/provider-error-reporting-sentry

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

Sentry-backed ErrorReporterPort provider for Beignet applications.

The provider installs ctx.ports.errorReporter using @sentry/node while keeping Sentry imports out of contracts, use cases, routes, and domain code.

Install

bun add @beignet/provider-error-reporting-sentry @beignet/core @sentry/node
Copy

Register

// server/providers.ts
import { createSentryErrorReportingProvider } from "@beignet/provider-error-reporting-sentry";

export const providers = [
  createSentryErrorReportingProvider({
    dsn: process.env.SENTRY_DSN,
    init: {
      environment: process.env.NODE_ENV,
    },
  }),
];
Copy

With no dsn or SENTRY_DSN, the provider still contributes the Beignet port but does not initialize Sentry. This is useful for local development that wants stable wiring before production secrets exist.

beignet doctor --strict checks that installed Sentry providers are registered in server/providers.ts. SENTRY_DSN is optional by metadata because local development may intentionally run with a no-op Sentry client.

Capture HTTP failures

Register createErrorReportingHooks(...) in server/index.ts so unexpected route and server failures are captured through ctx.ports.errorReporter.

import { createErrorReportingHooks } from "@beignet/core/server";
import { createNextServer, createNextServerLoader } from "@beignet/next";
import type { AppContext } from "@/app-context";
import { initialPorts } from "@/infra/port-wiring";
import { appContext } from "./context";
import { routes } from "./routes";

export const getServer = createNextServerLoader(async () => {
  const { providers } = await import("./providers");

  return createNextServer({
    ports: initialPorts,
    providers,
    hooks: [createErrorReportingHooks<AppContext>()],
    context: appContext,
    routes,
  });
});
Copy

The hook skips expected application catalog errors, auth denials, tenant requirements, idempotency conflicts, entitlement denials, and request validation failures by default. Use mapUnhandledError for response bodies; the hook only observes and reports.

Use

await ctx.ports.errorReporter.captureException(error, {
  level: "error",
  requestId: ctx.requestId,
  traceId: ctx.traceId,
  tags: {
    feature: "billing",
  },
  contexts: {
    tenant: { id: ctx.tenant.id },
  },
});
Copy

The provider also contributes ctx.ports.sentry as an escape hatch with the raw Sentry SDK and configured client.

Structured user metadata, tags, contexts, and extras pass through Beignet's default sensitive-key redaction before reaching Sentry. Add domain-specific keys with redaction; the defaults always remain active:

createSentryErrorReportingProvider({
  dsn: process.env.SENTRY_DSN,
  redaction: {
    sensitiveKeys: ["privateNote", "medicalRecord"],
  },
});
Copy

Redaction does not rewrite the captured exception message, stack, or arbitrary non-sensitive PII such as an explicitly supplied email address. Keep exception messages safe and use Sentry beforeSend or the raw escape hatch when an app needs domain-aware event filtering. Default HTTP hooks skip AppError instances and never copy AppError.details into report metadata; manual captures remain app-owned.

Devtools

Captured exceptions and messages are recorded as Beignet error instrumentation under the errors watcher when devtools or another instrumentation sink is installed before the provider.

API

createSentryErrorReporter(options)

Creates an ErrorReporterPort from a Sentry-compatible client. Use this for tests or custom provider composition.

createSentryErrorReportingProvider(options)

Creates a Beignet lifecycle provider that contributes:

• ctx.ports.errorReporter, the standard Beignet ErrorReporterPort
• ctx.ports.sentry, an escape hatch with the raw Sentry client and SDK

createSentryErrorReportingProvider()

Ready-to-register provider using the default Sentry singleton and process.env.SENTRY_DSN when present.

Failure behavior

captureException(...) and captureMessage(...) resolve after handing work to Sentry's SDK. With no configured DSN, the Beignet port is still present and capture calls become local no-ops apart from Beignet instrumentation. SDK transport failures follow Sentry's buffering and delivery behavior.

Local and tests

Leave SENTRY_DSN unset locally when you only need stable app wiring. Use a fake ErrorReporterPort in use-case tests and assert error-reporting hooks at the route/server boundary when the reporting behavior matters.

Deployment notes

Set SENTRY_DSN and Sentry environment/release metadata per deployed environment. Register createErrorReportingHooks(...) in server/index.ts if HTTP/server failures should be captured automatically.