feat(browser): Export functional integrations & deprecate classes (#10267)

mydea · web-flow · commit c5dcb5d16878 · 2024-01-23T14:44:14.000-05:00
Also deprecate the `Integrations` hash in browser SDKs.

I also forgot to add the integrations from `@sentry/integrations` to the
migration.md doc, so adding those as well!
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -34,17 +34,31 @@ integrations from the `Integrations.XXX` hash, is deprecated in favor of using t
 
 The following list shows how integrations should be migrated:
 
-| Old                      | New                             | Packages                                                                                                |
-| ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `new InboundFilters()`   | `inboundFiltersIntegration()`   | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
-| `new FunctionToString()` | `functionToStringIntegration()` | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
-| `new LinkedErrors()`     | `linkedErrorsIntegration()`     | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
-| `new ModuleMetadata()`   | `moduleMetadataIntegration()`   | `@sentry/core`, `@sentry/browser`                                                                       |
-| `new RequestData()`      | `requestDataIntegration()`      | `@sentry/core`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge`                    |
-| `new Wasm() `            | `wasmIntegration()`             | `@sentry/wasm`                                                                                          |
-| `new Replay()`           | `replayIntegration()`           | `@sentry/browser`                                                                                       |
-| `new ReplayCanvas()`     | `replayCanvasIntegration()`     | `@sentry/browser`                                                                                       |
-| `new Feedback()`         | `feedbackIntegration()`         | `@sentry/browser`                                                                                       |
+| Old                       | New                              | Packages                                                                                                |
+| ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `new InboundFilters()`    | `inboundFiltersIntegration()`    | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
+| `new FunctionToString()`  | `functionToStringIntegration()`  | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
+| `new LinkedErrors()`      | `linkedErrorsIntegration()`      | `@sentry/core`, `@sentry/browser`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge` |
+| `new ModuleMetadata()`    | `moduleMetadataIntegration()`    | `@sentry/core`, `@sentry/browser`                                                                       |
+| `new RequestData()`       | `requestDataIntegration()`       | `@sentry/core`, `@sentry/node`, `@sentry/deno`, `@sentry/bun`, `@sentry/vercel-edge`                    |
+| `new Wasm() `             | `wasmIntegration()`              | `@sentry/wasm`                                                                                          |
+| `new Replay()`            | `replayIntegration()`            | `@sentry/browser`                                                                                       |
+| `new ReplayCanvas()`      | `replayCanvasIntegration()`      | `@sentry/browser`                                                                                       |
+| `new Feedback()`          | `feedbackIntegration()`          | `@sentry/browser`                                                                                       |
+| `new CaptureConsole()`    | `captureConsoleIntegration()`    | `@sentry/integrations`                                                                                  |
+| `new Debug()`             | `debugIntegration()`             | `@sentry/integrations`                                                                                  |
+| `new Dedupe()`            | `dedupeIntegration()`            | `@sentry/browser`, `@sentry/integrations`, `@sentry/deno`                                               |
+| `new ExtraErrorData()`    | `extraErrorDataIntegration()`    | `@sentry/integrations`                                                                                  |
+| `new ReportingObserver()` | `reportingObserverIntegration()` | `@sentry/integrations`                                                                                  |
+| `new RewriteFrames()`     | `rewriteFramesIntegration()`     | `@sentry/integrations`                                                                                  |
+| `new SessionTiming()`     | `sessionTimingIntegration()`     | `@sentry/integrations`                                                                                  |
+| `new HttpClient()`        | `httpClientIntegration()`        | `@sentry/integrations`                                                                                  |
+| `new ContextLines()`      | `contextLinesIntegration()`      | `@sentry/browser`                                                                                       |
+| `new Breadcrumbs()`       | `breadcrumbsIntegration()`       | `@sentry/browser`, `@sentry/deno`                                                                       |
+| `new GlobalHandlers()`    | `globalHandlersIntegration()`    | `@sentry/browser`                                                                                       |
+| `new HttpContext()`       | `httpContextIntegration()`       | `@sentry/browser`                                                                                       |
+| `new TryCatch()`          | `browserApiErrorsIntegration()`  | `@sentry/browser`, `@sentry/deno`                                                                       |
+| `new VueIntegration()`    | `vueIntegration()`               | `@sentry/vue`                                                                                           |
 
 ## Deprecate `hub.bindClient()` and `makeMain()`
 
diff --git a/packages/astro/src/index.types.ts b/packages/astro/src/index.types.ts
@@ -14,8 +14,11 @@ import sentryAstro from './index.server';
 export declare function init(options: Options | clientSdk.BrowserOptions | serverSdk.NodeOptions): void;
 
 // We export a merged Integrations object so that users can (at least typing-wise) use all integrations everywhere.
+// eslint-disable-next-line deprecation/deprecation
 export declare const Integrations: typeof clientSdk.Integrations & typeof serverSdk.Integrations;
 
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+
 export declare const defaultIntegrations: Integration[];
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;
diff --git a/packages/browser/src/exports.ts b/packages/browser/src/exports.ts
@@ -102,4 +102,13 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   wrap,
 } from './sdk';
+
+export { breadcrumbsIntegration } from './integrations/breadcrumbs';
+export { dedupeIntegration } from './integrations/dedupe';
+export { globalHandlersIntegration } from './integrations/globalhandlers';
+export { httpContextIntegration } from './integrations/httpcontext';
+export { linkedErrorsIntegration } from './integrations/linkederrors';
+export { browserApiErrorsIntegration } from './integrations/trycatch';
+
+// eslint-disable-next-line deprecation/deprecation
 export { GlobalHandlers, TryCatch, Breadcrumbs, LinkedErrors, HttpContext, Dedupe } from './integrations';
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -12,13 +12,15 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
   windowIntegrations = WINDOW.Sentry.Integrations;
 }
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
 const INTEGRATIONS = {
   ...windowIntegrations,
   // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };
 
+// eslint-disable-next-line deprecation/deprecation
 export { INTEGRATIONS as Integrations };
 
 export {
diff --git a/packages/browser/src/integrations/breadcrumbs.ts b/packages/browser/src/integrations/breadcrumbs.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */
-import { addBreadcrumb, convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { addBreadcrumb, convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type {
   Client,
   Event as SentryEvent,
@@ -57,7 +57,7 @@ const MAX_ALLOWED_STRING_LENGTH = 1024;
 
 const INTEGRATION_NAME = 'Breadcrumbs';
 
-const breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
+const _breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
   const _options = {
     console: true,
     dom: true,
@@ -95,8 +95,12 @@ const breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
   };
 }) satisfies IntegrationFn;
 
+export const breadcrumbsIntegration = defineIntegration(_breadcrumbsIntegration);
+
 /**
  * Default Breadcrumbs instrumentations
+ *
+ * @deprecated Use `breadcrumbsIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const Breadcrumbs = convertIntegrationFnToClass(INTEGRATION_NAME, breadcrumbsIntegration) as IntegrationClass<
diff --git a/packages/browser/src/integrations/dedupe.ts b/packages/browser/src/integrations/dedupe.ts
@@ -1,12 +1,12 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Exception, Integration, IntegrationClass, IntegrationFn, StackFrame } from '@sentry/types';
 import { logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
 
 const INTEGRATION_NAME = 'Dedupe';
 
-const dedupeIntegration = (() => {
+const _dedupeIntegration = (() => {
   let previousEvent: Event | undefined;
 
   return {
@@ -33,7 +33,12 @@ const dedupeIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** Deduplication filter */
+export const dedupeIntegration = defineIntegration(_dedupeIntegration);
+
+/**
+ * Deduplication filter.
+ * @deprecated Use `dedupeIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const Dedupe = convertIntegrationFnToClass(INTEGRATION_NAME, dedupeIntegration) as IntegrationClass<
   Integration & { processEvent: (event: Event) => Event }
diff --git a/packages/browser/src/integrations/globalhandlers.ts b/packages/browser/src/integrations/globalhandlers.ts
@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
-import { captureEvent, convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { captureEvent, convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type {
   Client,
   Event,
@@ -30,7 +30,7 @@ type GlobalHandlersIntegrations = Record<GlobalHandlersIntegrationsOptionKeys, b
 
 const INTEGRATION_NAME = 'GlobalHandlers';
 
-const globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations> = {}) => {
+const _globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations> = {}) => {
   const _options = {
     onerror: true,
     onunhandledrejection: true,
@@ -55,7 +55,12 @@ const globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations>
   };
 }) satisfies IntegrationFn;
 
-/** Global handlers */
+export const globalHandlersIntegration = defineIntegration(_globalHandlersIntegration);
+
+/**
+ * Global handlers.
+ * @deprecated Use `globalHandlersIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const GlobalHandlers = convertIntegrationFnToClass(
   INTEGRATION_NAME,
diff --git a/packages/browser/src/integrations/httpcontext.ts b/packages/browser/src/integrations/httpcontext.ts
@@ -1,11 +1,11 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 
 import { WINDOW } from '../helpers';
 
 const INTEGRATION_NAME = 'HttpContext';
 
-const httpContextIntegration = (() => {
+const _httpContextIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -33,7 +33,12 @@ const httpContextIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** HttpContext integration collects information about HTTP request headers */
+export const httpContextIntegration = defineIntegration(_httpContextIntegration);
+
+/**
+ * HttpContext integration collects information about HTTP request headers.
+ * @deprecated Use `httpContextIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const HttpContext = convertIntegrationFnToClass(INTEGRATION_NAME, httpContextIntegration) as IntegrationClass<
   Integration & { preprocessEvent: (event: Event) => void }
diff --git a/packages/browser/src/integrations/index.ts b/packages/browser/src/integrations/index.ts
@@ -1,3 +1,4 @@
+/* eslint-disable deprecation/deprecation */
 export { GlobalHandlers } from './globalhandlers';
 export { TryCatch } from './trycatch';
 export { Breadcrumbs } from './breadcrumbs';
diff --git a/packages/browser/src/integrations/linkederrors.ts b/packages/browser/src/integrations/linkederrors.ts
@@ -1,4 +1,4 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { applyAggregateErrorsToEvent } from '@sentry/utils';
 import { exceptionFromError } from '../eventbuilder';
@@ -13,7 +13,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;
 
@@ -38,7 +38,12 @@ const linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
-/** Aggregrate linked errors in an event. */
+export const linkedErrorsIntegration = defineIntegration(_linkedErrorsIntegration);
+
+/**
+ * Aggregrate linked errors in 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 }
diff --git a/packages/browser/src/integrations/trycatch.ts b/packages/browser/src/integrations/trycatch.ts
@@ -1,4 +1,4 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Integration, IntegrationClass, IntegrationFn, WrappedFunction } from '@sentry/types';
 import { fill, getFunctionName, getOriginalFunction } from '@sentry/utils';
 
@@ -50,7 +50,7 @@ interface TryCatchOptions {
   eventTarget: boolean | string[];
 }
 
-const browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) => {
+const _browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) => {
   const _options = {
     XMLHttpRequest: true,
     eventTarget: true,
@@ -90,7 +90,12 @@ const browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) =>
   };
 }) satisfies IntegrationFn;
 
-/** Wrap timer functions and event targets to catch errors and provide better meta data */
+export const browserApiErrorsIntegration = defineIntegration(_browserApiErrorsIntegration);
+
+/**
+ * Wrap timer functions and event targets to catch errors and provide better meta data.
+ * @deprecated Use `browserApiErrorsIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const TryCatch = convertIntegrationFnToClass(
   INTEGRATION_NAME,
diff --git a/packages/browser/src/sdk.ts b/packages/browser/src/sdk.ts
@@ -1,7 +1,6 @@
 import type { Hub } from '@sentry/core';
+import { functionToStringIntegration, inboundFiltersIntegration } from '@sentry/core';
 import {
-  FunctionToString,
-  InboundFilters,
   captureSession,
   getClient,
   getCurrentHub,
@@ -23,22 +22,25 @@ import { BrowserClient } from './client';
 import { DEBUG_BUILD } from './debug-build';
 import type { ReportDialogOptions } from './helpers';
 import { WINDOW, wrap as internalWrap } from './helpers';
-import { Breadcrumbs, Dedupe, GlobalHandlers, HttpContext, LinkedErrors, TryCatch } from './integrations';
+import { breadcrumbsIntegration } from './integrations/breadcrumbs';
+import { dedupeIntegration } from './integrations/dedupe';
+import { globalHandlersIntegration } from './integrations/globalhandlers';
+import { httpContextIntegration } from './integrations/httpcontext';
+import { linkedErrorsIntegration } from './integrations/linkederrors';
+import { browserApiErrorsIntegration } from './integrations/trycatch';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport, makeXHRTransport } from './transports';
 
 /** @deprecated Use `getDefaultIntegrations(options)` instead. */
 export const defaultIntegrations = [
-  /* eslint-disable deprecation/deprecation */
-  new InboundFilters(),
-  new FunctionToString(),
-  /* eslint-enable deprecation/deprecation */
-  new TryCatch(),
-  new Breadcrumbs(),
-  new GlobalHandlers(),
-  new LinkedErrors(),
-  new Dedupe(),
-  new HttpContext(),
+  inboundFiltersIntegration(),
+  functionToStringIntegration(),
+  browserApiErrorsIntegration(),
+  breadcrumbsIntegration(),
+  globalHandlersIntegration(),
+  linkedErrorsIntegration(),
+  dedupeIntegration(),
+  httpContextIntegration(),
 ];
 
 /** Get the default integrations for the browser SDK. */
diff --git a/packages/browser/test/unit/integrations/breadcrumbs.test.ts b/packages/browser/test/unit/integrations/breadcrumbs.test.ts
@@ -8,6 +8,7 @@ describe('Breadcrumbs', () => {
     const client = new BrowserClient({
       ...getDefaultBrowserClientOptions(),
       dsn: 'https://username@domain/123',
+      // eslint-disable-next-line deprecation/deprecation
       integrations: [new Breadcrumbs()],
     });
 
diff --git a/packages/deno/src/index.ts b/packages/deno/src/index.ts
@@ -94,6 +94,7 @@ export {
   init,
 } from './sdk';
 
+export { breadcrumbsIntegration, dedupeIntegration } from '@sentry/browser';
 import { Integrations as CoreIntegrations } from '@sentry/core';
 
 import * as DenoIntegrations from './integrations';
diff --git a/packages/deno/src/sdk.ts b/packages/deno/src/sdk.ts
@@ -1,6 +1,6 @@
-import { Breadcrumbs, Dedupe } from '@sentry/browser';
+import { breadcrumbsIntegration, dedupeIntegration } from '@sentry/browser';
 import type { ServerRuntimeClientOptions } from '@sentry/core';
-import { FunctionToString, InboundFilters, LinkedErrors } from '@sentry/core';
+import { functionToStringIntegration, inboundFiltersIntegration, linkedErrorsIntegration } from '@sentry/core';
 import { getIntegrationsToSetup, initAndBind } from '@sentry/core';
 import type { Integration, Options, StackParser } from '@sentry/types';
 import { createStackParser, nodeStackLineParser, stackParserFromStackParserOptions } from '@sentry/utils';
@@ -12,15 +12,13 @@ import type { DenoOptions } from './types';
 
 /** @deprecated Use `getDefaultIntegrations(options)` instead. */
 export const defaultIntegrations = [
-  /* eslint-disable deprecation/deprecation */
   // Common
-  new InboundFilters(),
-  new FunctionToString(),
-  new LinkedErrors(),
-  /* eslint-enable deprecation/deprecation */
+  inboundFiltersIntegration(),
+  functionToStringIntegration(),
+  linkedErrorsIntegration(),
   // From Browser
-  new Dedupe(),
-  new Breadcrumbs({
+  dedupeIntegration(),
+  breadcrumbsIntegration({
     dom: false,
     history: false,
     xhr: false,
diff --git a/packages/nextjs/src/client/index.ts b/packages/nextjs/src/client/index.ts
@@ -18,7 +18,9 @@ export * from '@sentry/react';
 export { nextRouterInstrumentation } from './routing/nextRoutingInstrumentation';
 export { captureUnderscoreErrorException } from '../common/_error';
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
 export const Integrations = {
+  // eslint-disable-next-line deprecation/deprecation
   ...OriginalIntegrations,
   BrowserTracing,
 };
diff --git a/packages/nextjs/src/index.types.ts b/packages/nextjs/src/index.types.ts
@@ -20,10 +20,13 @@ export declare function init(
 ): void;
 
 // We export a merged Integrations object so that users can (at least typing-wise) use all integrations everywhere.
+// eslint-disable-next-line deprecation/deprecation
 export declare const Integrations: typeof clientSdk.Integrations &
   typeof serverSdk.Integrations &
   typeof edgeSdk.Integrations;
 
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+
 export declare const defaultIntegrations: Integration[];
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;
diff --git a/packages/nextjs/test/clientSdk.test.ts b/packages/nextjs/test/clientSdk.test.ts
diff --git a/packages/remix/src/index.types.ts b/packages/remix/src/index.types.ts
diff --git a/packages/sveltekit/src/index.types.ts b/packages/sveltekit/src/index.types.ts

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable deprecation/deprecation */`
`1`	`2`	`export { GlobalHandlers } from './globalhandlers';`
`2`	`3`	`export { TryCatch } from './trycatch';`
`3`	`4`	`export { Breadcrumbs } from './breadcrumbs';`