@beignet/provider-error-reporting-sentry

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

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,
    },
  }),
];

With no dsn or SENTRY_DSN, the provider still contributes the Beignet port but does not initialize Sentry. This is useful for examples and local apps that want 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 and example apps 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 } from "@beignet/next";
import type { AppContext } from "@/app-context";
import { appPorts } from "@/infra/app-ports";
import { appContext } from "./context";
import { providers } from "./providers";
import { routes } from "./routes";

export const server = await createNextServer({
  ports: appPorts,
  providers,
  hooks: [createErrorReportingHooks<AppContext>()],
  context: appContext,
  routes,
});

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 },
  },
});

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

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

sentryErrorReportingProvider

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.