feat(core): Deprecate hub.bindClient() & makeMain() (#10188)

Instead, users should use `setCurrentClient()` & `client.init()`.

For now, we can't fully replace our own test usages of this everywhere,
as we need it to test a clean hub state. But for users, there should be
a reasonable path forward for 99% of cases. I added a docs page
outlining how the different scenarios will work in v8 (and already
should work now, too).

Author: mydea

.size-limit.js

@@ -72,7 +72,7 @@ module.exports = [
     name: '@sentry/browser (incl. Tracing) - ES6 CDN Bundle (gzipped)',
     path: 'packages/browser/build/bundles/bundle.tracing.min.js',
     gzip: true,
-    limit: '35 KB',
+    limit: '37 KB',
   },
   {
     name: '@sentry/browser - ES6 CDN Bundle (gzipped)',
@@ -94,7 +94,7 @@ module.exports = [
     path: 'packages/browser/build/bundles/bundle.tracing.min.js',
     gzip: false,
     brotli: false,
-    limit: '100 KB',
+    limit: '105 KB',
   },
   {
     name: '@sentry/browser - ES6 CDN Bundle (minified & uncompressed)',

MIGRATION.md

@@ -10,7 +10,12 @@ 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!
 
-## Deprecated `Transaction` integration
+## Deprecate `hub.bindClient()` and `makeMain()`
+
+Instead, either directly use `initAndBind()`, or the new APIs `setCurrentClient()` and `client.init()`. See
+[Initializing the SDK in v8](./docs/v8-initializing.md) for more details.
+
+## Deprecate `Transaction` integration
 
 This pluggable integration from `@sentry/integrations` will be removed in v8. It was already undocumented and is not
 necessary for the SDK to work as expected.

docs/v8-initializing.md

@@ -0,0 +1,65 @@
+# Initializing the SDK in v8
+
+In v8, manual initialization of the SDK will work as follows.
+
+## Classic initialization
+
+```ts
+import * as Sentry from '@sentry/browser';
+
+Sentry.init({
+  dsn: 'xxx',
+});
+```
+
+This will initialize the SDK with all defaults & make it the currently active Sentry instance. This will continue to use
+the existing global, isolation & current scope, and just bind the client to it.
+
+## Using multiple clients in Node
+
+In an environment with multiple execution contexts (e.g. Node), you can setup multiple clients that are active for
+different contexts, like this:
+
+```js
+import * as Sentry from '@sentry/browser';
+
+// Sets up the _default_ client
+Sentry.init({
+  dsn: 'xxx',
+});
+
+// One execution context with client A
+Sentry.withScope(() => {
+  const clientA = new Client();
+  Sentry.setCurrentClient(clientA); // binds this client to the current execution context only!
+  clientA.init();
+});
+
+// One execution context with client B
+Sentry.withScope(() => {
+  const clientB = new Client();
+  Sentry.setCurrentClient(clientB); // binds this client to the current execution context only!
+  clientB.init();
+});
+```
+
+## Using multiple clients in Browser
+
+In environments without execution contexts, like the browser, you can only ever have a single active client. You can,
+however, create further clients and use them manually:
+
+```js
+// Default client - this is used everywhere
+Sentry.init({
+  dsn: 'xxx',
+});
+
+// Setup a manual client
+const clientA = new Client();
+const scope = new Scope();
+scope.setClient(clientA);
+// You can capture exceptions manually for this client like this:
+scope.captureException();
+```
+
+This is also necessary e.g. if you have a browser extension or some other code that runs in a shared environment.

packages/astro/src/index.server.ts

@@ -31,7 +31,9 @@ export {
   getGlobalScope,
   getIsolationScope,
   Hub,
+  // eslint-disable-next-line deprecation/deprecation
   makeMain,
+  setCurrentClient,
   Scope,
   // eslint-disable-next-line deprecation/deprecation
   startTransaction,

packages/browser/src/exports.ts

@@ -43,7 +43,10 @@ export {
   Hub,
   // eslint-disable-next-line deprecation/deprecation
   lastEventId,
+  // eslint-disable-next-line deprecation/deprecation
+  // eslint-disable-next-line deprecation/deprecation
   makeMain,
+  setCurrentClient,
   Scope,
   // eslint-disable-next-line deprecation/deprecation
   startTransaction,

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

@@ -3,6 +3,7 @@ import type { WrappedFunction } from '@sentry/types';
 import * as utils from '@sentry/utils';
 
 import type { Event } from '../../src';
+import { setCurrentClient } from '../../src';
 import {
   BrowserClient,
   Integrations,
@@ -14,7 +15,6 @@ import {
   captureMessage,
   flush,
   getClient,
-  getCurrentHub,
   getCurrentScope,
   init,
   showReportDialog,
@@ -86,7 +86,7 @@ describe('SentryBrowser', () => {
       const client = new BrowserClient(options);
       it('uses the user on the scope', () => {
         getCurrentScope().setUser(EX_USER);
-        getCurrentHub().bindClient(client);
+        setCurrentClient(client);
 
         // eslint-disable-next-line deprecation/deprecation
         showReportDialog();
@@ -100,7 +100,7 @@ describe('SentryBrowser', () => {
 
       it('prioritizes options user over scope user', () => {
         getCurrentScope().setUser(EX_USER);
-        getCurrentHub().bindClient(client);
+        setCurrentClient(client);
 
         const DIALOG_OPTION_USER = { email: '[email protected]' };
         // eslint-disable-next-line deprecation/deprecation
@@ -216,7 +216,7 @@ describe('SentryBrowser', () => {
         },
         dsn,
       });
-      getCurrentHub().bindClient(new BrowserClient(options));
+      setCurrentClient(new BrowserClient(options));
       captureMessage('test');
     });
 
@@ -230,7 +230,7 @@ describe('SentryBrowser', () => {
         },
         dsn,
       });
-      getCurrentHub().bindClient(new BrowserClient(options));
+      setCurrentClient(new BrowserClient(options));
       captureEvent({ message: 'event' });
     });
 
@@ -243,7 +243,7 @@ describe('SentryBrowser', () => {
         },
         dsn,
       });
-      getCurrentHub().bindClient(new BrowserClient(options));
+      setCurrentClient(new BrowserClient(options));
       captureEvent({ message: 'event' });
     });
 
@@ -254,7 +254,7 @@ describe('SentryBrowser', () => {
         dsn,
         integrations: [],
       });
-      getCurrentHub().bindClient(new BrowserClient(options));
+      setCurrentClient(new BrowserClient(options));
 
       captureMessage('event222');
       captureMessage('event222');
@@ -271,7 +271,9 @@ describe('SentryBrowser', () => {
         dsn,
         integrations: [new Integrations.InboundFilters({ ignoreErrors: ['capture'] })],
       });
-      getCurrentHub().bindClient(new BrowserClient(options));
+      const client = new BrowserClient(options);
+      setCurrentClient(client);
+      client.init();
 
       captureMessage('capture');
 
@@ -405,7 +407,7 @@ describe('wrap()', () => {
       },
       dsn,
     });
-    getCurrentHub().bindClient(new BrowserClient(options));
+    setCurrentClient(new BrowserClient(options));
 
     try {
       // eslint-disable-next-line deprecation/deprecation

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

@@ -1,30 +1,18 @@
 import * as SentryCore from '@sentry/core';
-import type { Client } from '@sentry/types';
 
-import { Breadcrumbs, BrowserClient, Hub, flush } from '../../../src';
+import { Breadcrumbs, BrowserClient, flush } from '../../../src';
 import { getDefaultBrowserClientOptions } from '../helper/browser-client-options';
 
-const hub = new Hub();
-let client: Client | undefined;
-
-jest.mock('@sentry/core', () => {
-  const original = jest.requireActual('@sentry/core');
-  return {
-    ...original,
-    getCurrentHub: () => hub,
-    getClient: () => client,
-  };
-});
-
 describe('Breadcrumbs', () => {
   it('Should add sentry breadcrumb', async () => {
-    client = new BrowserClient({
+    const client = new BrowserClient({
       ...getDefaultBrowserClientOptions(),
       dsn: 'https://username@domain/123',
       integrations: [new Breadcrumbs()],
     });
 
-    SentryCore.getCurrentHub().bindClient(client);
+    SentryCore.setCurrentClient(client);
+    client.init();
 
     const addBreadcrumbSpy = jest.spyOn(SentryCore, 'addBreadcrumb').mockImplementation(() => {});
 

packages/browser/test/unit/profiling/hubextensions.test.ts

@@ -47,6 +47,7 @@ describe('BrowserProfilingIntegration', () => {
       },
     };
 
+    // eslint-disable-next-line deprecation/deprecation
     hub.bindClient(client);
   });
 

packages/bun/src/index.ts

@@ -50,7 +50,9 @@ export {
   Hub,
   // eslint-disable-next-line deprecation/deprecation
   lastEventId,
+  // eslint-disable-next-line deprecation/deprecation
   makeMain,
+  setCurrentClient,
   runWithAsyncContext,
   Scope,
   // eslint-disable-next-line deprecation/deprecation

packages/bun/test/integrations/bunserver.test.ts

@@ -20,6 +20,7 @@ describe('Bun Serve Integration', () => {
     const options = getDefaultBunClientOptions({ tracesSampleRate: 1, debug: true });
     client = new BunClient(options);
     hub = new Hub(client);
+    // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
   });