feat(toolbar): Add setup instructions for the Sentry Toolbar using the react hook useSentryToolbar

docs/product/sentry-toolbar/faq.mdx

@@ -0,0 +1,66 @@
+---
+title: FAQ
+sidebar_order: 30
+description: "Frequently asked questions about the Sentry Toolbar."
+---
+
+<Expandable permalink title="In what environments should I enable the Toolbar?">
+
+Since the Sentry Toolbar will be visible to users within your app, it's important to consider which environments should render it.
+
+If your web application requires authentication to access:
+- In development and staging, always initialized the Sentry Toolbar.
+- In production conditionally initialize the Sentry Toolbar when an employee is logged in.
+
+If you web application does not require authenticaion:
+- In development and staging environments initialize the Toolbar at all times.
+- In production environments, do not initialize the Toolbar.
+
+Initializing the Sentry Toolbar allows all developers and testers to quickly go from the page they're looking at, back to Sentry for further debugging.
+In production it can make it easier for developers to reproduce issues, but it should not be initialized for all users of the site -- only when an employee/engineer/etc visits.
+
+Once you decide where and when you want the Toolbar to appear, you'll write those conditions into your codebase. The specific implementation is something you'll need to write based on how your app works and how your team is set up.
+
+</Expandable>
+
+<Expandable permalink title="How can I conditionally initialize the Toolbar?">
+
+Implementing the specific conditions for initializing the Toolbar will vary from app to app and which ever framework or template library is in use.
+
+For example, the conditions to show show the Toolbar in development and staging might look like this, if written in JavaScript:
+
+```html {tabTitle:CDN}
+<script>
+const env = process.env.ENVIRONMENT || 'development';
+const isDev = env === 'development' || env === 'staging';
+
+if (isDev) {
+  window.SentryToolbar.init({ ... });
+}
+</script>
+```
+```javascript {tabTitle:React}
+const env = process.env.ENVIRONMENT || 'development';
+const isDev = env === 'development' || env === 'staging';
+
+useSentryToolbar({
+  enabled: isDev,
+  initProps: {
+    ...
+  },
+})
+```
+
+</Expandable>
+
+<Expandable permalink title="Are there plans to include the Toolbar in the JavaScript SDK?">
+
+The [Sentry Toolbar](https://github.com/getsentry/sentry-toolbar) and the [JavaScript SDK](https://github.com/getsentry/sentry-javascript) are distinct features that we intentionally keep separated.
+
+Some of the differences between the two include:
+  - The Toolbar is a UI product focused on making it easier to find and take action on existing data, while the SDK functions as infrastructure to collect and send data to the server.
+  - The Toolbar has a different set of [dependencies](https://github.com/getsentry/sentry-toolbar/blob/main/package.json) and uses different browser APIs that the JavaScript SDK does not use. For example: the Toolbar will interact with things like cookies and local storage. By keeping these pieces of code separate, it's easier to audit the [SDK code on GitHub](https://github.com/getsentry/sentry-javascript) to verify that it is not persisting information inside end-users' browsers.
+  - The setup and deploy instruction are very different. The SDK is best deployed on staging and production environments, and can be configured easily with environment variables. The Sentry Toolbar requires special considerations to deploy it into production, usually by creating a condition so that it's only included for members of your own Sentry organization.
+
+</Expandable>
+

docs/product/dev-toolbar/setup.mdx → docs/product/sentry-toolbar/setup.mdx

@@ -1,133 +1,158 @@
 ---
-title: "Set Up Dev Toolbar"
+title: "Set Up Sentry Toolbar"
 sidebar_order: 10
-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."
+description: "Get started with Sentry's Toolbar, bringing critical Sentry insights and tools into your web app to help your team troubleshoot more effectively."
 ---
 
 <Alert>
-  The Dev Toolbar is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on
+  The Sentry Toolbar is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on
   [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns.
 </Alert>
 
 ## Pre-Requisites
 
-For the Sentry Dev Toolbar to work best, [enable tracing](/platforms/javascript/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.
+For the Sentry Toolbar to work best, [enable tracing](/platforms/javascript/tracing/) in your app. With tracing enabled, the Sentry Toolbar will be able to associate issues and feedback with the current URL in the browser location.
 
-## 1. Choose Deploy Environments
+## 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.
+Since the Sentry 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 Sentry Toolbar?"_](/product/sentry-toolbar/faq/#in-what-environments-should-i-enable-the-dev-toolbar) for tips.
 
-In dev and staging environments, 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.
+You will need to edit the [Project Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) 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.
 
-In production environments, the Dev Toolbar can make it easier to reproduce real issues your users are having. However the Toolbar should not be rendered for all users of the site -- only when an employee/engineer/etc visits.
+![Sentry's Toolbar Settings Page](./img/sentry-project-settings-toolbar.png)
 
-Once you decide where and when you want the Toolbar to appear, you'll write those conditions into your codebase. The specific implementation is something you'll need to write based on how your app works and how your dev team is set up.
+## 2. Install
 
-For example, the conditions to show show the Toolbar in dev and staging might look like this:
+If you are developing a React based application, it's time to add the Toolbar into your `package.json` file.
 
-```typescript
-const env = process.env.SENTRY_ENVIRONMENT || 'development';
+Or, you can skip ahead to the next step to find the CDN configuration instructions.
 
-const isDev = env === 'development' || env === 'staging';
-if (isDev) {
-  // Enable the Dev Toolbar here...
-}
+```bash {tabTitle: npm}
+npm install --save @sentry/toolbar
+```
+```bash {tabTitle: yarn}
+yarn add @sentry/toolbar
 ```
 
-Or 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.
-
-## 2. Allow Domains
-
-You will need to edit the [Project Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) page to allow the Toolbar to connect to Sentry by configuring your dev, staging, and production domains. Only add domains that you trust and control to this list.
+## 3. Configure
 
-![Sentry's Dev Toolbar Settings Page](./img/sentry-project-settings-toolbar.png)
+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.
 
-## 3. Install
+```javascript {tabTitle: React}
+import {useSentryToolbar} from '@sentry/toolbar';
 
-Next you must include the Toolbar code in your app:
+useSentryToolbar({
+  // Remember to conditionally enable the Toolbar.
+  // This will reduce network traffic for users
+  // who do not have credentials to login to Sentry.
+  enabled,
 
-```html {tabTitle: CDN}
-<!--
-Put this at the bottom of your page
-so it doesn’t block other critical JavaScript.
--->
-<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
-```
-```typescript {tabTitle: React}
-// An NPM package is under development
-// In the meantime, go here for instructions to create a React hook manually:
-//   https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md
+  initProps: {
+    organizationSlug: 'acme',
+    projectIdOrSlug: 'website',
+  },
+})
 ```
-
-Remember to conditionally include the Toolbar code only in environments that need it. This will help reduce network traffic for your users who do not have the credentials needed to login.
-
-## 4. Configure
-
-Finally, call `SentryToolbar.init(initConfig)` to render a Toolbar instance on each page where you want to see the Dev Toolbar. This will prompt any visitor to the page to login to your Sentry organization.
-
 ```html {tabTitle: CDN}
 <html>
 <head>...</head>
 <body>
     ...
+    <!--
+    Put this at the bottom of your page so it doesn’t
+    block other critical JavaScript.
+
+    Remember to conditionally include the Toolbar
+    script. This will reduce network traffic for users
+    who do not have credentials to login to Sentry.
+    -->
     <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
     <script>
-    window.SentryToolbar.init({ ... });
+    window.SentryToolbar.init({
+      organizationSlug: 'acme',
+      projectIdOrSlug: 'website',
+    });
     </script>
 </body>
 </html>
 ```
-```typescript {tabTitle:React}
-// An NPM package is under development
-// In the meantime, go here for instructions to create a React hook manually:
-//   https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md
-```
-
-If the toolbar `<script>` is 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 login.
 
+See the [FAQ: _"How can I conditionally initialize the Toolbar?"_](/product/sentry-toolbar/faq/#how-can-i-conditionally-initialize-the-toolbar) for help implementing conditions for different environments.
 
 ### Init Configuration Options
 
-At minimum, you should be calling `.init()` with these two options:
-```javascript
-window.SentryToolbar.init({
-  organizationSlug: 'acme',
-  projectIdOrSlug: 'website',
-});
-```
+At minimum, you must set `organizationSlug` and `projectIdOrSlug`.
 
-And you can also include any additional options from this list:
+The complete list of options is here:
 
 | Option | Type | Description | Default Value |
-| ----- | ----- | ----- | ----- |
+| ------ | ---- | ----------- | ------------- |
 | `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* |
 | `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* |
 | `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` |
 | `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the Toolbar on the screen. | `'right-edge'` |
 | `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` |
-| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Feature Flag Panel](/product/dev-toolbar/setup//#feature-flag-Panel) below | `undefined` |
+| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Feature Flag Panel](/product/sentry-toolbar/setup//#feature-flag-Panel) below | `undefined` |
 | `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'` |
 | `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the Toolbar html. | `'sentry-toolbar'` |
 | `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` |
 | `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the Toolbar in the DOM. | `document.body` |
 
+
+The React hook supports some other top-level options. The defaults values are:
+
+```javascript {tabTitle:React}
+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',
+})
+```
+
+| Options | Type | Description | Default Value |
+| ------- | ---- | ----------- | ------------- |
+| `enabled` | `booleand (optional)` | Conditionally initialize the toolbar. Set this to false to avoid requesting the toolbar code on the browser, or to safely unmount an existing toolbar instance | `true` |
+| `version` | `string (optional)` | Request a speicifc version of the toolbar from the CDN. It's recommended to use `latest` for automatic updates. See https://github.com/getsentry/sentry-toolbar/releases for a list of available release tags. | `'latest'` |
+| `cdn` | `string (optional)` | Overrides the `version` field above. Setting the CDN is useful if you want to self-host a specific version of the Toolbar. | `'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`.
+
 ```javascript
 const unmountToolbar = window.SentryToolbar.init({ ... });
 
 // sometime later...
 unmountToolbar();
 ```
+```javascript {tabTitle:React}
+useSentryToolbar({
+  enabled: false, // The toolbar will not be mounted
+  initProps: {
+    ...
+  },
+})
+```
 
 ## Feature Flag Panel
 
 <Alert>
   If you're using feature flags inside your product then also setup [Feature Flag Evaluation and Change Tracking](/platforms/javascript/feature-flags/) within your SDK.
 </Alert>
 
-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.
+In order to integrate your feature flagging platform with the Sentry 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](https://github.com/open-feature/js-sdk-contrib). To use it, call the `SentryToolbar.OpenFeatureAdapter` implementation.
 

redirects.js

@@ -230,6 +230,14 @@ const userDocsRedirects = [
     source: '/organization/integrations/msteams/',
     destination: '/organization/integrations/notification-incidents/msteams/',
   },
+  {
+    source: '/product/dev-toolbar/setup/',
+    destination: '/product/sentry-toolbar/setup/',
+  },
+  {
+    source: '/product/dev-toolbar/faq/',
+    destination: '/product/sentry-toolbar/faq/',
+  },
   {
     source: '/product/explore/session-replay/hydration-errors/',
     destination: '/product/issues/issue-details/replay-issues/hydration-error/',