|
| 1 | +--- |
| 2 | +title: "Set Up" |
| 3 | +sidebar_order: 10 |
| 4 | +description: "Get started with Sentry's Dev Toolbar, bringing critical Sentry insights and tools into your web app to help your team troubleshoot more effectively." |
| 5 | +--- |
| 6 | + |
| 7 | +<Alert level="info"> |
| 8 | + The Dev Toolbar is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on |
| 9 | + [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns. |
| 10 | +</Alert> |
| 11 | + |
| 12 | +## Set Up Your Web App |
| 13 | + |
| 14 | +<Alert level="warning"> |
| 15 | + [Enabling tracing](/platforms/javascript/tracing/) is a prerequisite to using the Developer Toolbar. Tracing is used to collect page-specific issues and feedback through transactions. |
| 16 | +</Alert> |
| 17 | + |
| 18 | +You need to complete two steps to get the toolbar rendered on the page: |
| 19 | +1. Add or dynamically inject the following script into your web app: |
| 20 | + ```html |
| 21 | + <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
| 22 | + ``` |
| 23 | + It is recommended that you add the script tag at the bottom of the page so it doesn’t block other critical JavaScript. |
| 24 | + |
| 25 | +2. Call `window.SentryToolbar.init(initConfig)` to set up a toolbar instance on each page where you want to see the Dev Toolbar. |
| 26 | + ```html |
| 27 | + <html> |
| 28 | + <head>...</head> |
| 29 | + <body> |
| 30 | + … |
| 31 | + <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
| 32 | + <script> |
| 33 | + window.SentryToolbar.init({ … }); |
| 34 | + </script> |
| 35 | + </body> |
| 36 | + </html> |
| 37 | + ``` |
| 38 | + |
| 39 | +### Unmounting The Toolbar |
| 40 | + |
| 41 | +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. |
| 42 | +```html |
| 43 | +<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
| 44 | +<script> |
| 45 | + const unmountToolbar = window.SentryToolbar.init({ … }); |
| 46 | +
|
| 47 | + // sometime later... |
| 48 | + unmountToolbar(); |
| 49 | +</script> |
| 50 | +``` |
| 51 | + |
| 52 | +## Init Configuration Options |
| 53 | + |
| 54 | +The following options can be passed into the `.init()` function. |
| 55 | + |
| 56 | +At minimum, you should be calling `.init()` with these three options: |
| 57 | +```javascript |
| 58 | +window.SentryToolbar.init({ |
| 59 | + organizationSlug: 'acme', |
| 60 | + projectIdOrSlug: 'website', |
| 61 | + environment: 'production' |
| 62 | +}); |
| 63 | +``` |
| 64 | +And you can include any additional options from this list: |
| 65 | + |
| 66 | +| Option | Type | Description | Default Value | |
| 67 | +| ----- | ----- | ----- | ----- | |
| 68 | +| `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* | |
| 69 | +| `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* | |
| 70 | +| `environment (optional)` | `string \| string[] \| undefined` | The environment of this deployment. Used to narrow search results in the Toolbar UI. Set to `undefined` or `""` or `[]` if you want to see results from all environments. | `undefined` | |
| 71 | +| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the toolbar on the screen. | `'right-edge'` | |
| 72 | +| `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` | |
| 73 | +| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) below | `undefined` | |
| 74 | +| `sentryOrigin (optional)` | `string \| undefined` | The origin where Sentry can be found. Used for loading the connection to Sentry, and generating links to the website. For example: `'https://acme.sentry.io'` | `'https://sentry.io'` | |
| 75 | +| `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the toolbar html. | `'sentry-toolbar'` | |
| 76 | +| `debug (optional)` | `string \| undefined` | A comma separated string of debug targets to enable. Example: `'logging,state'`. If the list contains 'all' or 'true' then all targets will be enabled. Valid targets: `'logging' 'login-success' 'settings' 'state'` | `undefined` | |
| 77 | +| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the toolbar in the DOM. | `document.body` | |
| 78 | + |
| 79 | +## Implement Feature Flag Adapter |
| 80 | + |
| 81 | +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, and also store and retrieve a list of overrides to apply to your local browser session. |
| 82 | + |
| 83 | +We plan to [create adapters for OpenFeature and LaunchDarkly](https://github.com/getsentry/sentry-toolbar/issues/150) soon. |
| 84 | + |
| 85 | +The adapter interface is: |
| 86 | +```javascript |
| 87 | +type FlagValue = boolean | string | number | undefined; |
| 88 | +type FlagMap = Record<string, FlagValue>; |
| 89 | +interface FeatureFlagAdapter { |
| 90 | + /** |
| 91 | + * All known flag names and their evaluated values. |
| 92 | + */ |
| 93 | + getFlagMap: () => Promise<FlagMap>; |
| 94 | + |
| 95 | + /** |
| 96 | + * Any overridden or manually set flags and values. |
| 97 | + */ |
| 98 | + getOverrides: () => Promise<FlagMap>; |
| 99 | + |
| 100 | + /** |
| 101 | + * Manually set a flag to be a specific value, overriding the evaluated value. |
| 102 | + */ |
| 103 | + setOverride: (name: string, override: FlagValue) => void; |
| 104 | + |
| 105 | + /** |
| 106 | + * A callback to clear all overrides from this browser. |
| 107 | + */ |
| 108 | + clearOverrides: () => void; |
| 109 | + |
| 110 | + /** |
| 111 | + * Deeplink into your external feature-flag provider and find out more about |
| 112 | + * this specific flag. |
| 113 | + */ |
| 114 | + urlTemplate?: undefined | ((name: string) => string | URL | undefined); |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +[MockFeatureFlagIntegration.tsx](https://github.com/getsentry/sentry-toolbar/blob/301c31d561a81e3fd8ffc9532aad3a60af685916/src/env/demo/MockFeatureFlagIntegration.tsx) is an example adapter to use as a reference. |
| 119 | + |
| 120 | + |
| 121 | +## Deploying To Dev, Staging, and Production Environments |
| 122 | +Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments the toolbar should apply to. |
| 123 | + |
| 124 | +In dev and staging environments, you might want to *unconditionally* include the toolbar so that all developers and testers can use it and quickly go from the page they're looking at back to Sentry for further debugging. |
| 125 | + |
| 126 | +In production however, it's strongly recommended to *conditionally* include the Dev Toolbar `<script>` tag so that only members of your Sentry organization can see it. The specific implementation for conditionally including the Dev Toolbar is something you'll need to write based on how your app works and how your dev team is set up. |
| 127 | + |
| 128 | +For example, if your web application requires authentication to access, you could add a conditional where the Dev Toolbar is shown always when deployed to development **and** staging, but in production only show the toolbar **if** an employee is logged in. |
| 129 | + |
| 130 | + |
| 131 | +The code might look like this: |
| 132 | +```javascript |
| 133 | +// example conditions to render the toolbar in different environments. |
| 134 | + |
| 135 | +const env = process.env.SENTRY_ENVIRONMENT || 'development'; |
| 136 | +const isEmployee = user.email.endsWith('@joshys-pizza.com') |
| 137 | + |
| 138 | +const isDev = env === 'development' || env === 'staging'; |
| 139 | +const isEmployeeInProd = env === 'production' && isEmployee; |
| 140 | +if (isDev || isEmployeeInProd) { |
| 141 | + SentryToolbar.init({ ... }); |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +If the toolbar `<script>` is accidentally included on your site, and `SentryToolbar.init()` is called, then a "Login to Sentry" button will be visible to the public. This is not ideal, but your data in Sentry will still be safe as users outside of your Sentry organization will not be able to authenticate themselves. |
| 146 | + |
| 147 | +## Conditionally Inserting Script Tag |
| 148 | + |
| 149 | +It's possible to dynamically insert the script tag inside a single-page app, prior to calling `SentryToolbar.init()`, so that it’s only visible to authorized users. See [`docs/conditional-script.md`](https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md) for example code. This will help reduce network traffic for your users because they do not have the credentials needed to login. |
| 150 | +This example code will be eventually implemented as an NPM package, but for now it can be done manually. |
0 commit comments