Shared Environments / Browser Extensions

Learn how to use Sentry in shared environments (for example in browser extensions or VSCode extensions).

These best practices are relevant for you if you set up Sentry in one of the following use-cases:

  • Browser Extensions
  • VSCode Extensions
  • Third-Party Widgets
  • Plugin Architecture
  • Libraries
  • Any other scenario where you might have multiple Sentry instances running in the same environment

When setting up Sentry in a shared environment where multiple Sentry instances may run, you should not use Sentry.init(), as this will pollute the global state. If your browser extension uses Sentry.init(), and a website also uses Sentry, the extension may send events to the website's Sentry project, or vice versa.

For such scenarios, you have to set up a client manually as seen in the example below. In addition, you should also avoid adding any integrations that use global state, like Breadcrumbs or GlobalHandlers. Furthermore, some default integrations that use the global state have to be filtered as in the example below. 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.

Copied
import {
  BrowserClient,
  defaultStackParser,
  getDefaultIntegrations,
  makeFetchTransport,
  Scope,
} from "@sentry/browser";

// filter integrations that use the global variable
const integrations = getDefaultIntegrations({}).filter(
  (defaultIntegration) => {
    return !["BrowserApiErrors", "Breadcrumbs", "GlobalHandlers"].includes(
      defaultIntegration.name,
    );
  },
);

const client = new BrowserClient({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  integrations: integrations,
});

const scope = new Scope();
scope.setClient(client);

client.init(); // initializing has to be done after setting the client on the scope

// You can capture exceptions manually for this client like this:
scope.captureException(new Error("example"));

To make it a bit simpler but somewhat still maintain "Let Sentry handle unhandled errors" you can use the following code:

Copied
// Init Sentry as shown above

try {
  // Your goes code here
  // as in import and execute your code here
  // and if an error occurs, Sentry will capture it
} catch (error) {
  scope.captureException(error);
}

If you notice that Sentry is not capturing error events from the browser extension, try disabling the Browser extension errors option in the Inbound Filters of your Sentry configuration. Read more about Inbound Filters in the product documentation under Inbound filters.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").