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

.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: 'option@example.com' };
         // 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);
   });
 

packages/core/src/hub.ts

@@ -147,6 +147,7 @@ export class Hub implements HubInterface {
     this._stack = [{ scope: assignedScope }];
 
     if (client) {
+      // eslint-disable-next-line deprecation/deprecation
       this.bindClient(client);
     }
 
@@ -166,7 +167,10 @@ export class Hub implements HubInterface {
   }
 
   /**
-   * @inheritDoc
+   * This binds the given client to the current scope.
+   * @param client An SDK client (client) instance.
+   *
+   * @deprecated Use `initAndBind()` directly, or `setCurrentClient()` and/or `client.init()` instead.
    */
   public bindClient(client?: Client): void {
     // eslint-disable-next-line deprecation/deprecation
@@ -488,10 +492,12 @@ export class Hub implements HubInterface {
    * @inheritDoc
    */
   public run(callback: (hub: Hub) => void): void {
+    // eslint-disable-next-line deprecation/deprecation
     const oldHub = makeMain(this);
     try {
       callback(this);
     } finally {
+      // eslint-disable-next-line deprecation/deprecation
       makeMain(oldHub);
     }
   }
@@ -690,6 +696,8 @@ export function getMainCarrier(): Carrier {
  * Replaces the current main hub with the passed one on the global object
  *
  * @returns The old replaced hub
+ *
+ * @deprecated Use `setCurrentClient()` instead.
  */
 export function makeMain(hub: Hub): Hub {
   const registry = getMainCarrier();

packages/core/src/index.ts

@@ -41,6 +41,7 @@ export {
   getIsolationScope,
   getHubFromCarrier,
   Hub,
+  // eslint-disable-next-line deprecation/deprecation
   makeMain,
   getMainCarrier,
   runWithAsyncContext,
@@ -59,7 +60,7 @@ export {
 export { getEnvelopeEndpointWithUrlEncodedAuth, getReportDialogEndpoint } from './api';
 export { BaseClient, addEventProcessor } from './baseclient';
 export { ServerRuntimeClient } from './server-runtime-client';
-export { initAndBind } from './sdk';
+export { initAndBind, setCurrentClient } from './sdk';
 export { createTransport } from './transports/base';
 export { makeOfflineTransport } from './transports/offline';
 export { makeMultiplexedTransport } from './transports/multiplexed';

packages/core/src/sdk.ts

@@ -35,5 +35,32 @@ export function initAndBind<F extends Client, O extends ClientOptions>(
   scope.update(options.initialScope);
 
   const client = new clientClass(options);
-  hub.bindClient(client);
+  setCurrentClient(client);
+  initializeClient(client);
+}
+
+/**
+ * Make the given client the current client.
+ */
+export function setCurrentClient(client: Client): void {
+  const hub = getCurrentHub();
+  // eslint-disable-next-line deprecation/deprecation
+  const top = hub.getStackTop();
+  top.client = client;
+  top.scope.setClient(client);
+}
+
+/**
+ * Initialize the client for the current scope.
+ * Make sure to call this after `setCurrentClient()`.
+ */
+function initializeClient(client: Client): void {
+  if (client.init) {
+    client.init();
+    // TODO v8: Remove this fallback
+    // eslint-disable-next-line deprecation/deprecation
+  } else if (client.setupIntegrations) {
+    // eslint-disable-next-line deprecation/deprecation
+    client.setupIntegrations();
+  }
 }

packages/core/test/lib/exports.test.ts

@@ -30,6 +30,7 @@ describe('withScope', () => {
   beforeEach(() => {
     const client = getTestClient();
     const hub = new Hub(client);
+    // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
   });
 
@@ -171,6 +172,7 @@ describe('session APIs', () => {
   beforeEach(() => {
     const client = getTestClient();
     const hub = new Hub(client);
+    // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
   });
 

packages/core/test/lib/integration.test.ts

@@ -618,6 +618,7 @@ describe('addIntegration', () => {
 
     const client = getTestClient();
     const hub = new Hub(client);
+    // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
 
     const integration = new CustomIntegration();
@@ -635,6 +636,7 @@ describe('addIntegration', () => {
     }
 
     const hub = new Hub();
+    // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
 
     const integration = new CustomIntegration();