agentic-dev-template/docs/library-decisions/2026-05-14-@sentry/nextjs.md

package, version, tier, decision, date, deciders, adr, filter-results, verification-commands, accepted-cves

package	version	tier	decision	date	deciders	adr	filter-results	verification-commands	accepted-cves
@sentry/nextjs	^10.51.0	core	approved	2026-05-14	Danijel Martinek	adr-014	license types maintenance boundary-fit shadow-check eu-residency cve-scan named-consumer socketRisk MIT native active pass pass ok clean pass clean	npm view @sentry/nextjs license npm view @sentry/nextjs version pnpm audit --audit-level=moderate

Filter: license

npm view @sentry/nextjs license returns MIT. MIT is on the allowlist.

Filter: types

@sentry/nextjs is authored in TypeScript and ships its own .d.ts declaration files. No separate @types/ package is needed.

Filter: maintenance

Actively maintained by Sentry Inc. The 10.x line sees regular releases tracking Next.js releases. Used by thousands of production Next.js apps; issue tracker shows prompt engagement.

Filter: boundary-fit

ADR-014 designates Sentry as the error-capture and tracing backend. The ESLint no-restricted-imports rule (ADR-014 §6) allowlists @sentry/* only within core-shared/instrumentation/sentry/**, the apps' instrumentation*.{ts,mjs} / next.config.{mjs} entry points, and the core-testing/setup/no-sentry.ts mock. Feature packages MUST NOT import @sentry/* directly — they consume only the vendor-neutral ITracer/ILogger interfaces.

Filter: shadow-check

@sentry/nextjs is the sole Next.js error-monitoring SDK in the workspace. No competing APM or crash-reporter library (Datadog, New Relic, Rollbar, Bugsnag) is present or proposed.

Filter: eu-residency

Sentry offers EU-region data residency (hosted at de.sentry.io). The workspace's WEB_NEXT_SENTRY_DSN can point to an EU-hosted project; the SDK routes all payloads to the DSN host. PII scrubbing at the OTel processor layer (ADR-017, ADR-014 §4) ensures only scrubbed data leaves the process.

Filter: cve-scan

pnpm audit --audit-level=moderate reports no advisories against @sentry/nextjs at the time of this trace.

Filter: named-consumer

packages/core-shared/src/instrumentation/sentry/ holds the Sentry adapter pair (SentryTracer, SentryLogger). apps/web-next/instrumentation.ts and apps/web-next/next.config.mjs are the concrete Next.js-side consumers. Both are named, non-hypothetical consumers.

Prompt: replaces

No prior error monitoring or distributed tracing library was in place. @sentry/nextjs replaces ad-hoc console.error logging that provided no stack context, no distributed trace correlation, and no session replay for diagnosing reproduction steps.

Prompt: migration-cost-out

Moderate. The interface boundary (ADR-014 §1) limits feature-package blast radius to zero — feature code never imports @sentry/nextjs. Removal would require swapping the SentryTracer/SentryLogger adapter pair in core-shared/instrumentation/sentry/ for a new adapter, updating apps/web-next/instrumentation.ts and next.config.mjs, and dropping the WEB_NEXT_SENTRY_DSN env var. The scope is bounded and mechanical.

Prompt: alternatives-considered

1. Datadog APM — Stronger distributed tracing primitives, but higher cost, heavier SDK footprint, and no built-in session replay. Evaluated and deferred.
2. New Relic — Enterprise-grade but requires a New Relic account and agent; no native Next.js SDK at the time of evaluation.
3. Direct OpenTelemetry export — Deferred to ADR-017 for the OTel migration layer; Sentry remains the exporter via @sentry/opentelemetry bridge.

See ADR-014 for the full decision rationale.