ref: Make it easier to use stackParser (#5015)

Co-authored-by: Luca Forstner <[email protected]>

Author: AbhiPrasad

MIGRATION.md

@@ -32,6 +32,42 @@ import {
 } from '@sentry/minimal';
 ```
 
+## Explicit Client Options
+
+In v7, we've updated the `Client` to have options seperate from the options passed into `Sentry.init`. This means that constructing a client now requires 3 options: `integrations`, `transport` and `stackParser`. These can be customized as you see fit.
+
+```ts
+import { BrowserClient, defaultStackParser, defaultIntegrations, makeFetchTransport } from '@sentry/browser';
+
+// New in v7:
+const client = new BrowserClient({
+  transport: makeFetchTransport,
+  stackParser: defaultStackParser,
+  integrations: [...defaultIntegrations],
+});
+
+// Before:
+const client = new BrowserClient();
+```
+
+Since you now explicitly pass in the dependencies of the client, you can also tree-shake out dependencies that you do not use this way. For example, you can tree-shake out the SDK's default integrations and only use the ones that you want like so:
+
+```ts
+import { BrowserClient, defaultStackParser, Integrations, makeFetchTransport } from '@sentry/browser';
+
+// New in v7:
+const client = new BrowserClient({
+  transport: makeFetchTransport,
+  stackParser: defaultStackParser,
+  integrations: [
+    new Integrations.Breadcrumbs(),
+    new Integrations.GlobalHandlers(),
+    new Integrations.LinkedErrors(),
+    new Integrations.Dedupe(),
+  ],
+});
+```
+
 ## Removal Of Old Platform Integrations From `@sentry/integrations` Package
 
 The following classes will be removed from the `@sentry/integrations` package and can no longer be used:

packages/browser/src/eventbuilder.ts

@@ -14,7 +14,7 @@ import {
 } from '@sentry/utils';
 
 /**
- * This function creates an exception from an TraceKitStackTrace
+ * This function creates an exception from a JavaScript Error
  */
 export function exceptionFromError(stackParser: StackParser, ex: Error): Exception {
   // Get the frames first since Opera can lose the stack if we touch anything else first

packages/browser/src/exports.ts

@@ -44,13 +44,15 @@ export {
 } from '@sentry/core';
 
 export { BrowserClient } from './client';
+export { makeFetchTransport, makeXHRTransport } from './transports';
 export {
-  defaultStackParsers,
-  chromeStackParser,
-  geckoStackParser,
-  opera10StackParser,
-  opera11StackParser,
-  winjsStackParser,
+  defaultStackParser,
+  defaultStackLineParsers,
+  chromeStackLineParser,
+  geckoStackLineParser,
+  opera10StackLineParser,
+  opera11StackLineParser,
+  winjsStackLineParser,
 } from './stack-parsers';
 export { defaultIntegrations, forceLoad, init, lastEventId, onLoad, showReportDialog, flush, close, wrap } from './sdk';
 export { SDK_NAME } from './version';

packages/browser/src/index.ts

@@ -4,7 +4,6 @@ import { Integrations as CoreIntegrations } from '@sentry/core';
 import { getGlobalObject } from '@sentry/utils';
 
 import * as BrowserIntegrations from './integrations';
-import * as Transports from './transports';
 
 let windowIntegrations = {};
 
@@ -20,4 +19,4 @@ const INTEGRATIONS = {
   ...BrowserIntegrations,
 };
 
-export { INTEGRATIONS as Integrations, Transports };
+export { INTEGRATIONS as Integrations };

packages/browser/src/sdk.ts

@@ -11,15 +11,15 @@ import {
   getGlobalObject,
   logger,
   resolvedSyncPromise,
-  stackParserFromOptions,
+  stackParserFromStackParserOptions,
   supportsFetch,
 } from '@sentry/utils';
 
 import { BrowserClient, BrowserClientOptions, BrowserOptions } from './client';
 import { IS_DEBUG_BUILD } from './flags';
 import { ReportDialogOptions, wrap as internalWrap } from './helpers';
 import { Breadcrumbs, Dedupe, GlobalHandlers, LinkedErrors, TryCatch, UserAgent } from './integrations';
-import { defaultStackParsers } from './stack-parsers';
+import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport, makeXHRTransport } from './transports';
 
 export const defaultIntegrations = [
@@ -110,7 +110,7 @@ export function init(options: BrowserOptions = {}): void {
 
   const clientOptions: BrowserClientOptions = {
     ...options,
-    stackParser: stackParserFromOptions(options.stackParser || defaultStackParsers),
+    stackParser: stackParserFromStackParserOptions(options.stackParser || defaultStackParser),
     integrations: getIntegrationsToSetup(options),
     transport: options.transport || (supportsFetch() ? makeFetchTransport : makeXHRTransport),
   };

packages/browser/src/stack-parsers.ts

@@ -1,4 +1,5 @@
 import { StackFrame, StackLineParser, StackLineParserFn } from '@sentry/types';
+import { createStackParser } from '@sentry/utils';
 
 // global reference to slice
 const UNKNOWN_FUNCTION = '?';
@@ -60,7 +61,7 @@ const chrome: StackLineParserFn = line => {
   return;
 };
 
-export const chromeStackParser: StackLineParser = [CHROME_PRIORITY, chrome];
+export const chromeStackLineParser: StackLineParser = [CHROME_PRIORITY, chrome];
 
 // gecko regex: `(?:bundle|\d+\.js)`: `bundle` is for react native, `\d+\.js` also but specifically for ram bundles because it
 // generates filenames without a prefix like `file://` the filenames in the stacktrace are just 42.js
@@ -96,7 +97,7 @@ const gecko: StackLineParserFn = line => {
   return;
 };
 
-export const geckoStackParser: StackLineParser = [GECKO_PRIORITY, gecko];
+export const geckoStackLineParser: StackLineParser = [GECKO_PRIORITY, gecko];
 
 const winjsRegex =
   /^\s*at (?:((?:\[object object\])?.+) )?\(?((?:file|ms-appx|https?|webpack|blob):.*?):(\d+)(?::(\d+))?\)?\s*$/i;
@@ -109,7 +110,7 @@ const winjs: StackLineParserFn = line => {
     : undefined;
 };
 
-export const winjsStackParser: StackLineParser = [WINJS_PRIORITY, winjs];
+export const winjsStackLineParser: StackLineParser = [WINJS_PRIORITY, winjs];
 
 const opera10Regex = / line (\d+).*script (?:in )?(\S+)(?:: in function (\S+))?$/i;
 
@@ -118,7 +119,7 @@ const opera10: StackLineParserFn = line => {
   return parts ? createFrame(parts[2], parts[3] || UNKNOWN_FUNCTION, +parts[1]) : undefined;
 };
 
-export const opera10StackParser: StackLineParser = [OPERA10_PRIORITY, opera10];
+export const opera10StackLineParser: StackLineParser = [OPERA10_PRIORITY, opera10];
 
 const opera11Regex =
   / line (\d+), column (\d+)\s*(?:in (?:<anonymous function: ([^>]+)>|([^)]+))\(.*\))? in (.*):\s*$/i;
@@ -128,9 +129,11 @@ const opera11: StackLineParserFn = line => {
   return parts ? createFrame(parts[5], parts[3] || parts[4] || UNKNOWN_FUNCTION, +parts[1], +parts[2]) : undefined;
 };
 
-export const opera11StackParser: StackLineParser = [OPERA11_PRIORITY, opera11];
+export const opera11StackLineParser: StackLineParser = [OPERA11_PRIORITY, opera11];
 
-export const defaultStackParsers = [chromeStackParser, geckoStackParser, winjsStackParser];
+export const defaultStackLineParsers = [chromeStackLineParser, geckoStackLineParser, winjsStackLineParser];
+
+export const defaultStackParser = createStackParser(...defaultStackLineParsers);
 
 /**
  * Safari web extensions, starting version unknown, can produce "frames-only" stacktraces.

packages/browser/test/unit/integrations/linkederrors.test.ts

@@ -1,13 +1,10 @@
 import { Event as SentryEvent, Exception, ExtendedError } from '@sentry/types';
-import { createStackParser } from '@sentry/utils';
 
 import { BrowserClient } from '../../../src/client';
 import * as LinkedErrorsModule from '../../../src/integrations/linkederrors';
-import { defaultStackParsers } from '../../../src/stack-parsers';
+import { defaultStackParser as parser } from '../../../src/stack-parsers';
 import { getDefaultBrowserClientOptions } from '../helper/browser-client-options';
 
-const parser = createStackParser(...defaultStackParsers);
-
 type EventWithException = SentryEvent & {
   exception: {
     values: Exception[];

packages/browser/test/unit/tracekit/chromium.test.ts

@@ -1,9 +1,5 @@
-import { createStackParser } from '@sentry/utils';
-
 import { exceptionFromError } from '../../../src/eventbuilder';
-import { defaultStackParsers } from '../../../src/stack-parsers';
-
-const parser = createStackParser(...defaultStackParsers);
+import { defaultStackParser as parser } from '../../../src/stack-parsers';
 
 describe('Tracekit - Chrome Tests', () => {
   it('should parse Chrome error with no location', () => {

packages/browser/test/unit/tracekit/firefox.test.ts

@@ -1,9 +1,5 @@
-import { createStackParser } from '@sentry/utils';
-
 import { exceptionFromError } from '../../../src/eventbuilder';
-import { defaultStackParsers } from '../../../src/stack-parsers';
-
-const parser = createStackParser(...defaultStackParsers);
+import { defaultStackParser as parser } from '../../../src/stack-parsers';
 
 describe('Tracekit - Firefox Tests', () => {
   it('should parse Firefox 3 error', () => {

packages/browser/test/unit/tracekit/ie.test.ts

@@ -1,9 +1,5 @@
-import { createStackParser } from '@sentry/utils';
-
 import { exceptionFromError } from '../../../src/eventbuilder';
-import { defaultStackParsers } from '../../../src/stack-parsers';
-
-const parser = createStackParser(...defaultStackParsers);
+import { defaultStackParser as parser } from '../../../src/stack-parsers';
 
 describe('Tracekit - IE Tests', () => {
   it('should parse IE 10 error', () => {