Skip to content

Commit 1087eb8

Browse files
mydeashanamatthews
andauthored
fix: Update docs for manual client creation (#8495)
--------- Co-authored-by: Shana Matthews <[email protected]>
1 parent d23e46e commit 1087eb8

File tree

1 file changed

+16
-38
lines changed
  • src/platforms/javascript/common/troubleshooting

1 file changed

+16
-38
lines changed

src/platforms/javascript/common/troubleshooting/index.mdx

Lines changed: 16 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,7 @@ import {
255255
defaultStackParser,
256256
defaultIntegrations,
257257
makeFetchTransport,
258+
Hub,
258259
} from "@sentry/browser";
259260

260261
const client = new BrowserClient({
@@ -264,53 +265,30 @@ const client = new BrowserClient({
264265
integrations: defaultIntegrations,
265266
});
266267

267-
client.captureException(new Error("example"));
268-
```
269-
270-
While the above sample should work perfectly fine, some methods like `configureScope` and `withScope` are missing on the `Client` because the `Hub` takes care of the state management. That's why it may be easier to create a new `Hub` and bind your `Client` to it. The result is the same but you will also get state management with it.
271-
272-
<SignInNote />
273-
274-
```javascript
275-
import {
276-
BrowserClient,
277-
defaultStackParser,
278-
defaultIntegrations,
279-
makeFetchTransport,
280-
} from "@sentry/browser";
281-
282-
const client = new BrowserClient({
283-
dsn: "___PUBLIC_DSN___",
284-
transport: makeFetchTransport,
285-
stackParser: defaultStackParser,
286-
integrations: defaultIntegrations,
287-
});
288-
268+
// You have to bind the client to a hub, otherwise integrations will not run!
289269
const hub = new Hub(client);
270+
// Or, if you already have a hub you want to re-use, you can also do:
271+
// hub.bindClient(client);
290272

291-
hub.configureScope(function (scope) {
292-
scope.setTag("a", "b");
293-
});
273+
hub.captureException(new Error("example"));
274+
```
294275

295-
hub.addBreadcrumb({ message: "crumb 1" });
296-
hub.captureMessage("test");
276+
You can now customize the hub to your liking, without affecting other hubs/clients.
297277

298-
try {
299-
a = b;
300-
} catch (e) {
301-
hub.captureException(e);
302-
}
278+
### Setting up Sentry in shared environments (e.g. Browser Extensions)
303279

304-
hub.withScope(function (scope) {
305-
hub.addBreadcrumb({ message: "crumb 2" });
306-
hub.captureMessage("test2");
307-
});
308-
```
280+
When setting up Sentry in a shared environment where multiple Sentry instances may run, for example, in a browser extension or similar, you should **not use `Sentry.init()`**, as this will pollute the global state. If your browser extension uses `Sentry.init()`, and the website the extension is running on also uses Sentry, the extension may send events to the website's Sentry project, or vice versa.
281+
282+
For such scenarios, you have to set up a client manually as seen in the example above.
283+
In addition, you should also avoid adding any integrations that use global state, like `Breadcrumbs` or `TryCatch`.
284+
As a rule of thumb, it's best to avoid using any integrations and to rely on manual capture of errors only in such scenarios.
309285

310286
### Dealing with Integrations
311287

312288
Integrations are setup on the `Client`, if you need to deal with multiple clients and hubs you have to make sure to also do the integration handling correctly.
313-
Here is a working example of how to use multiple clients with multiple hubs running global integrations.
289+
290+
We do not recommend doing this if you are using Sentry in a browser extension or in similar scenarios.
291+
If you can't avoid using global integrations (e.g. in a micro frontend application), here is a working example of how to use multiple clients with multiple hubs running global integrations.
314292

315293
<SignInNote />
316294

0 commit comments

Comments
 (0)