feat(core): Deprecate integration classes & Integrations.X

Instead, export the functional components from core, which users should directly use.

Author: mydea

MIGRATION.md

@@ -10,6 +10,24 @@ npx @sentry/migr8@latest
 This will let you select which updates to run, and automatically update your code. Make sure to still review all code
 changes!
 
+## Deprecate class-based integrations
+
+In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Integrations.ContextLines()]`. In
+v8, integrations will not be classes anymore, but instead functions. Both the use as a class, as well as accessing
+integrations from the `Integrations.XXX` hash, is deprecated in favor of using the new functional integrations
+
+- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`.
+
+The following list shows how integrations should be migrated:
+
+| Old                      | New                             |
+| ------------------------ | ------------------------------- |
+| `new InboundFilters()`   | `inboundFiltersIntegrations()`  |
+| `new FunctionToString()` | `functionToStringIntegration()` |
+| `new LinkedErrors()`     | `linkedErrorsIntegration()`     |
+| `new ModuleMetadata()`   | `moduleMetadataIntegration()`   |
+| `new RequestData()`      | `requestDataIntegration()`      |
+
 ## Deprecated `Transaction` integration
 
 This pluggable integration from `@sentry/integrations` will be removed in v8. It was already undocumented and is not

packages/browser/src/exports.ts

@@ -61,9 +61,13 @@ export {
   setUser,
   withScope,
   withIsolationScope,
+  // eslint-disable-next-line deprecation/deprecation
   FunctionToString,
+  // eslint-disable-next-line deprecation/deprecation
   InboundFilters,
   metrics,
+  functionToStringIntegration,
+  inboundFiltersIntegration,
 } from '@sentry/core';
 
 export { WINDOW } from './helpers';

packages/browser/src/index.bundle.base.ts

@@ -16,6 +16,7 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INTEGRATIONS: Record<string, new (...args: any[]) => Integration> = {
   ...windowIntegrations,
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };

packages/browser/src/index.ts

@@ -14,6 +14,7 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
 
 const INTEGRATIONS = {
   ...windowIntegrations,
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };
@@ -52,7 +53,9 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   makeMultiplexedTransport,
+  // eslint-disable-next-line deprecation/deprecation
   ModuleMetadata,
+  moduleMetadataIntegration,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export type { Span } from '@sentry/types';

packages/browser/src/sdk.ts

@@ -1,6 +1,7 @@
 import type { Hub } from '@sentry/core';
 import {
-  Integrations as CoreIntegrations,
+  FunctionToString,
+  InboundFilters,
   captureSession,
   getClient,
   getCurrentHub,
@@ -26,16 +27,18 @@ import { Breadcrumbs, Dedupe, GlobalHandlers, HttpContext, LinkedErrors, TryCatc
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport, makeXHRTransport } from './transports';
 
+/* eslint-disable deprecation/deprecation */
 export const defaultIntegrations = [
-  new CoreIntegrations.InboundFilters(),
-  new CoreIntegrations.FunctionToString(),
+  new InboundFilters(),
+  new FunctionToString(),
   new TryCatch(),
   new Breadcrumbs(),
   new GlobalHandlers(),
   new LinkedErrors(),
   new Dedupe(),
   new HttpContext(),
 ];
+/* eslint-enable deprecation/deprecation */
 
 /**
  * A magic string that build tooling can leverage in order to inject a release value into the SDK.

packages/browser/test/unit/index.test.ts

@@ -1,11 +1,10 @@
-import { SDK_VERSION, getReportDialogEndpoint } from '@sentry/core';
+import { InboundFilters, SDK_VERSION, getReportDialogEndpoint } from '@sentry/core';
 import type { WrappedFunction } from '@sentry/types';
 import * as utils from '@sentry/utils';
 
 import type { Event } from '../../src';
 import {
   BrowserClient,
-  Integrations,
   Scope,
   WINDOW,
   addBreadcrumb,
@@ -269,7 +268,10 @@ describe('SentryBrowser', () => {
       const options = getDefaultBrowserClientOptions({
         beforeSend: localBeforeSend,
         dsn,
-        integrations: [new Integrations.InboundFilters({ ignoreErrors: ['capture'] })],
+        integrations: [
+          // eslint-disable-next-line deprecation/deprecation
+          new InboundFilters({ ignoreErrors: ['capture'] }),
+        ],
       });
       getCurrentHub().bindClient(new BrowserClient(options));
 

packages/bun/src/index.ts

@@ -76,6 +76,11 @@ export {
   startSpanManual,
   continueTrace,
   metrics,
+  functionToStringIntegration,
+  inboundFiltersIntegration,
+  linkedErrorsIntegration,
+  moduleMetadataIntegration,
+  requestDataIntegration,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export { autoDiscoverNodePerformanceMonitoringIntegrations, cron } from '@sentry/node';
@@ -89,6 +94,7 @@ import { Integrations as NodeIntegrations } from '@sentry/node';
 import * as BunIntegrations from './integrations';
 
 const INTEGRATIONS = {
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...NodeIntegrations,
   ...BunIntegrations,

packages/bun/src/sdk.ts

@@ -1,17 +1,18 @@
 /* eslint-disable max-lines */
-import { Integrations as CoreIntegrations } from '@sentry/core';
+import { FunctionToString, InboundFilters, LinkedErrors } from '@sentry/core';
 import { Integrations as NodeIntegrations, init as initNode } from '@sentry/node';
 
 import { BunClient } from './client';
 import { BunServer } from './integrations';
 import { makeFetchTransport } from './transports';
 import type { BunOptions } from './types';
 
+/* eslint-disable deprecation/deprecation */
 export const defaultIntegrations = [
   // Common
-  new CoreIntegrations.InboundFilters(),
-  new CoreIntegrations.FunctionToString(),
-  new CoreIntegrations.LinkedErrors(),
+  new InboundFilters(),
+  new FunctionToString(),
+  new LinkedErrors(),
   // Native Wrappers
   new NodeIntegrations.Console(),
   new NodeIntegrations.Http(),
@@ -28,6 +29,7 @@ export const defaultIntegrations = [
   // Bun Specific
   new BunServer(),
 ];
+/* eslint-enable deprecation/deprecation */
 
 /**
  * The Sentry Bun SDK Client.

packages/core/src/index.ts

@@ -67,10 +67,10 @@ export { SDK_VERSION } from './version';
 export {
   getIntegrationsToSetup,
   addIntegration,
+  defineIntegration,
   // eslint-disable-next-line deprecation/deprecation
   convertIntegrationFnToClass,
 } from './integration';
-export { FunctionToString, InboundFilters, LinkedErrors } from './integrations';
 export { applyScopeDataToEvent, mergeScopeData } from './utils/applyScopeDataToEvent';
 export { prepareEvent } from './utils/prepareEvent';
 export { createCheckInEnvelope } from './checkin';
@@ -84,9 +84,20 @@ export {
 } from './utils/spanUtils';
 export { getRootSpan } from './utils/getRootSpan';
 export { DEFAULT_ENVIRONMENT } from './constants';
+/* eslint-disable deprecation/deprecation */
 export { ModuleMetadata } from './integrations/metadata';
 export { RequestData } from './integrations/requestdata';
-import * as Integrations from './integrations';
+/* eslint-enable deprecation/deprecation */
+import * as INTEGRATIONS from './integrations';
+export { functionToStringIntegration } from './integrations/functiontostring';
+export { inboundFiltersIntegration } from './integrations/inboundfilters';
+export { linkedErrorsIntegration } from './integrations/linkederrors';
+export { moduleMetadataIntegration } from './integrations/metadata';
+export { requestDataIntegration } from './integrations/requestdata';
 export { metrics } from './metrics/exports';
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
+const Integrations = INTEGRATIONS;
+
+// eslint-disable-next-line deprecation/deprecation
 export { Integrations };

packages/core/src/integration.ts

@@ -1,4 +1,13 @@
-import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn, Options } from '@sentry/types';
+import type {
+  Client,
+  Event,
+  EventHint,
+  Integration,
+  IntegrationClass,
+  IntegrationFn,
+  IntegrationFnResult,
+  Options,
+} from '@sentry/types';
 import { arrayify, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from './debug-build';
@@ -177,3 +186,11 @@ export function convertIntegrationFnToClass<Fn extends IntegrationFn>(
     { id: name },
   ) as unknown as IntegrationClass<Integration>;
 }
+
+/**
+ * Define an integration function that can be used to create an integration instance.
+ * Note that this by design hides the implementation details of the integration, as they are considered internal.
+ */
+export function defineIntegration<Fn extends IntegrationFn>(fn: Fn): (...args: Parameters<Fn>) => IntegrationFnResult {
+  return fn;
+}

packages/core/src/integrations/functiontostring.ts

@@ -1,12 +1,12 @@
 import type { Integration, IntegrationClass, IntegrationFn, WrappedFunction } from '@sentry/types';
 import { getOriginalFunction } from '@sentry/utils';
-import { convertIntegrationFnToClass } from '../integration';
+import { convertIntegrationFnToClass, defineIntegration } from '../integration';
 
 let originalFunctionToString: () => void;
 
 const INTEGRATION_NAME = 'FunctionToString';
 
-const functionToStringIntegration = (() => {
+const _functionToStringIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
@@ -28,7 +28,12 @@ const functionToStringIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** Patch toString calls to return proper name for wrapped functions */
+export const functionToStringIntegration = defineIntegration(_functionToStringIntegration);
+
+/**
+ * Patch toString calls to return proper name for wrapped functions.
+ * @deprecated Use `functionToStringIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const FunctionToString = convertIntegrationFnToClass(
   INTEGRATION_NAME,

packages/core/src/integrations/inboundfilters.ts

@@ -2,7 +2,7 @@ import type { Client, Event, EventHint, Integration, IntegrationClass, Integrati
 import { getEventDescription, logger, stringMatchesSomePattern } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
-import { convertIntegrationFnToClass } from '../integration';
+import { convertIntegrationFnToClass, defineIntegration } from '../integration';
 
 // "Script error." is hard coded into browsers for errors that it can't read.
 // this is the result of a script being pulled in from an external domain and CORS.
@@ -30,7 +30,7 @@ export interface InboundFiltersOptions {
 }
 
 const INTEGRATION_NAME = 'InboundFilters';
-const inboundFiltersIntegration = ((options: Partial<InboundFiltersOptions> = {}) => {
+const _inboundFiltersIntegration = ((options: Partial<InboundFiltersOptions> = {}) => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -43,7 +43,12 @@ const inboundFiltersIntegration = ((options: Partial<InboundFiltersOptions> = {}
   };
 }) satisfies IntegrationFn;
 
-/** Inbound filters configurable by the user */
+export const inboundFiltersIntegration = defineIntegration(_inboundFiltersIntegration);
+
+/**
+ * Inbound filters configurable by the user.
+ * @deprecated Use `inboundFiltersIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const InboundFilters = convertIntegrationFnToClass(
   INTEGRATION_NAME,

packages/core/src/integrations/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable deprecation/deprecation */
 export { FunctionToString } from './functiontostring';
 export { InboundFilters } from './inboundfilters';
 export { LinkedErrors } from './linkederrors';

packages/core/src/integrations/linkederrors.ts

@@ -1,6 +1,6 @@
 import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { applyAggregateErrorsToEvent, exceptionFromError } from '@sentry/utils';
-import { convertIntegrationFnToClass } from '../integration';
+import { convertIntegrationFnToClass, defineIntegration } from '../integration';
 
 interface LinkedErrorsOptions {
   key?: string;
@@ -12,7 +12,7 @@ const DEFAULT_LIMIT = 5;
 
 const INTEGRATION_NAME = 'LinkedErrors';
 
-const linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
+const _linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
   const limit = options.limit || DEFAULT_LIMIT;
   const key = options.key || DEFAULT_KEY;
 
@@ -36,7 +36,12 @@ const linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
-/** Adds SDK info to an event. */
+export const linkedErrorsIntegration = defineIntegration(_linkedErrorsIntegration);
+
+/**
+ * Adds SDK info to an event.
+ * @deprecated Use `linkedErrorsIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const LinkedErrors = convertIntegrationFnToClass(INTEGRATION_NAME, linkedErrorsIntegration) as IntegrationClass<
   Integration & { preprocessEvent: (event: Event, hint: EventHint, client: Client) => void }

packages/core/src/integrations/metadata.ts

@@ -1,12 +1,12 @@
 import type { Client, Event, EventHint, EventItem, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { forEachEnvelopeItem } from '@sentry/utils';
-import { convertIntegrationFnToClass } from '../integration';
+import { convertIntegrationFnToClass, defineIntegration } from '../integration';
 
 import { addMetadataToStackFrames, stripMetadataFromStackFrames } from '../metadata';
 
 const INTEGRATION_NAME = 'ModuleMetadata';
 
-const moduleMetadataIntegration = (() => {
+const _moduleMetadataIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -39,6 +39,8 @@ const moduleMetadataIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
+export const moduleMetadataIntegration = defineIntegration(_moduleMetadataIntegration);
+
 /**
  * Adds module metadata to stack frames.
  *
@@ -47,6 +49,8 @@ const moduleMetadataIntegration = (() => {
  * When this integration is added, the metadata passed to the bundler plugin is added to the stack frames of all events
  * under the `module_metadata` property. This can be used to help in tagging or routing of events from different teams
  * our sources
+ *
+ * @deprecated Use `moduleMetadataIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const ModuleMetadata = convertIntegrationFnToClass(

packages/core/src/integrations/requestdata.ts

@@ -9,7 +9,7 @@ import type {
 } from '@sentry/types';
 import type { AddRequestDataToEventOptions, TransactionNamingScheme } from '@sentry/utils';
 import { addRequestDataToEvent, extractPathForTransaction } from '@sentry/utils';
-import { convertIntegrationFnToClass } from '../integration';
+import { convertIntegrationFnToClass, defineIntegration } from '../integration';
 import { spanToJSON } from '../utils/spanUtils';
 
 export type RequestDataIntegrationOptions = {
@@ -55,7 +55,7 @@ const DEFAULT_OPTIONS = {
 
 const INTEGRATION_NAME = 'RequestData';
 
-const requestDataIntegration = ((options: RequestDataIntegrationOptions = {}) => {
+const _requestDataIntegration = ((options: RequestDataIntegrationOptions = {}) => {
   const _addRequestData = addRequestDataToEvent;
   const _options: Required<RequestDataIntegrationOptions> = {
     ...DEFAULT_OPTIONS,
@@ -139,8 +139,13 @@ const requestDataIntegration = ((options: RequestDataIntegrationOptions = {}) =>
   };
 }) satisfies IntegrationFn;
 
-/** Add data about a request to an event. Primarily for use in Node-based SDKs, but included in `@sentry/integrations`
- * so it can be used in cross-platform SDKs like `@sentry/nextjs`. */
+export const requestDataIntegration = defineIntegration(_requestDataIntegration);
+
+/**
+ * Add data about a request to an event. Primarily for use in Node-based SDKs, but included in `@sentry/integrations`
+ * so it can be used in cross-platform SDKs like `@sentry/nextjs`.
+ * @deprecated Use `requestDataIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const RequestData = convertIntegrationFnToClass(INTEGRATION_NAME, requestDataIntegration) as IntegrationClass<
   Integration & { processEvent: (event: Event, hint: EventHint, client: Client) => Event }