Set Up Dev Toolbar

Pre-Requisites

For the Sentry Dev Toolbar to work best, enable tracing in your app. With tracing enabled, the Dev Toolbar will be able to associate issues and feedback with the current URL in the browser location.

1. Allow Domains

Since the Dev Toolbar will be visible to users within your app, it's important to consider which environments should render it. See the FAQ: "In what environments should I enable the Dev Toolbar?" for tips.

You will need to edit the Project Settings page to allow the Toolbar to connect to Sentry. Add any production, staging, or development domains to the list. Only add domains that you trust and control to this list.

2. Install

If you are developing a React based application, it's time to add the Toolbar into your package.json file.

Or, you can skip ahead to the next step to find the CDN configuration instructions.

npm install --save @sentry/developer-toolbar

3. Configure

Finally, whether you have a React application or are loading the Toolbar from the CDN you need to initialize the Toolbar using JavaScript. This will prompt any visitor to login to your Sentry organization.

import { useSentryToolbar } from "@sentry/developer-toolbar";

useSentryToolbar({
  // Remember to conditionally enable the Toolbar.
  // This will reduce network traffic for users
  // who do not have credentials to login to Sentry.
  enabled,

  initProps: {
    organizationSlug: "acme",
    projectIdOrSlug: "website",
  },
});

See the FAQ: "How can I conditionally initialize the Toolbar?" for help implementing conditions for different environments.

Init Configuration Options

At minimum, you must set organizationSlug and projectIdOrSlug.

The complete list of options is here:

The React hook supports some other top-level options. The defaults values are:

useSentryToolbar({
  initProps: {
    organizationSlug: "acme",
    projectIdOrSlug: "website",
  },

  // Optional:
  enabled: true,

  // Optional: Either `version` or `cdn`
  // If both are set then `cdn` will override `version`
  version: "latest",
  cdn: "https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js",
});

Unmounting the Toolbar

If you have called SentryToolbar.init({...}) to render the Toolbar, but now want to manually remove or unmount it from the page, you can call the cleanup function that is returned from init(). This will unmount all the injected HTML and CSS. Login credentials will not be removed, so you can re-insert the toolbar and still be authenticated.

If you are using the React hook, then the toolbar will unmount when the react component is unmounted. Or if you set enabled: false.

const unmountToolbar = window.SentryToolbar.init({ ... });

// sometime later...
unmountToolbar();

Feature Flag Panel

In order to integrate your feature flagging platform with the Dev Toolbar, you will need an adapter that can read flag data from your provider. It will also store and retrieve a list of overrides to apply to your local browser session.

There is a built-in OpenFeatureAdapter that is compatible with the open-feature/js-sdk-contrib. To use it, call the SentryToolbar.OpenFeatureAdapter implementation.

<script>
  // Define your provider
  const provider = new FlagdWebProvider({...});

  // Set the provider into the OpenFeature SDK
  OpenFeature.setProvider(provider);

  window.SentryToolbar.init({
    ...
    // Set the provider into the OpenFeatureAdapter
    featureFlags: window.SentryToolbar.OpenFeatureAdapter({provider})
  });
</script>

You can also create your own adapter by implementing the FeatureFlagAdapter interface.

The adapter interface is:

type FlagValue = boolean | string | number | undefined;
type FlagMap = Record<string, FlagValue>;
interface FeatureFlagAdapter {
  /**
   * All known flag names and their evaluated values.
   */
  getFlagMap: () => Promise<FlagMap>;

  /**
   * Any overridden or manually set flags and values.
   */
  getOverrides: () => Promise<FlagMap>;

  /**
   * Manually set a flag to be a specific value, overriding the evaluated value.
   */
  setOverride: (name: string, override: FlagValue) => void;

  /**
   * A callback to clear all overrides from this browser.
   */
  clearOverrides: () => void;

  /**
   * Deeplink into your external feature-flag provider and find out more about
   * this specific flag.
   */
  urlTemplate?: undefined | ((name: string) => string | URL | undefined);
}

MockFeatureFlagAdapter.tsx is an example adapter to use as a reference.