# LaunchDarkly developer toolbar

> This topic describes how to install and use the LaunchDarkly developer toolbar.

## Overview

This topic describes how to install and use the LaunchDarkly developer toolbar. You can install and configure the toolbar directly in your codebase, and use it in your browser during local development.

The toolbar lets you:

* View a list of feature flags in use for your project, and easily override values locally to test application behavior for flag variations
* Listen to incoming events, including flag evaluation events
* Easily identify missing feature flags and link to your LaunchDarkly project so you can create them

<Frame caption="An example of the developer toolbar in use.">
  ![An example of the developer toolbar in use.](file:59c6336e-0400-4328-b5fc-8dd282e05bdc)
</Frame>

## Prerequisites

To begin using the developer toolbar, you need:

* [A client-side ID for your LaunchDarkly environment](/home/account/environment/keys#copy-sdk-credentials)

## Installation

You can install the developer toolbar using React or using a CDN. In either method, it should be used only in a local dev environment. Be sure that you do not render it in hosted or production environments.

### Install using React

If you develop your front end using React, the `@launchdarkly/toolbar` package provides a React hook to configure and lazily-load the developer toolbar.

Depending on your package manager, install the package using one of the following methods:

<CodeBlock>
  <CodeBlock title="npm">
    ```bash
    npm install @launchdarkly/toolbar@latest
    ```
  </CodeBlock>

  <CodeBlock title="yarn">
    ```bash
    yarn add @launchdarkly/toolbar@latest
    ```
  </CodeBlock>

  <CodeBlock title="pnpm">
    ```bash
    pnpm add @launchdarkly/toolbar@latest
    ```
  </CodeBlock>
</CodeBlock>

After you install the package, navigate to the area of your application where you instantiate your LaunchDarkly React client. The developer toolbar uses two plugins to power its functionality, and those plugins also need to be passed into the LaunchDarkly React client.

To do this:

<CodeBlock>
  <CodeBlock title="Pass plugins to the client">
    ```js
    import { render } from 'react-dom';
    import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
    import { 
      useLaunchDarklyToolbar, 
      FlagOverridePlugin, 
      EventInterceptionPlugin 
    } from '@launchdarkly/toolbar';

    // Pass the same instance of these plugins into both the LaunchDarkly
    // React client as well as the developer toolbar
    const flagOverridePlugin = new FlagOverridePlugin();
    const eventInterceptionPlugin = new EventInterceptionPlugin();

    (async () => {
      const LDProvider = await asyncWithLDProvider({
        clientSideID: 'client-side-id-123abc',
        context: {
          kind: 'user',
          key: 'user-key-123abc',
          name: 'Sandy Smith',
          email: 'sandy@example.com',
        },
        options: {
          plugins: [
            flagOverridePlugin,
            eventInterceptionPlugin,
            // other plugins...
          ],
          // other options...
        },
      });

      function App() {
        // Initialize toolbar with the same plugin instances
        useLaunchDarklyToolbar({
          flagOverridePlugin, // For flag overrides (SDK Mode only)
          eventInterceptionPlugin, // For event monitoring (works in both modes)

          // OR Dev Server Mode: Connect to LaunchDarkly dev server
          devServerUrl: 'http://localhost:8080',
          projectKey: 'my-project', // Optional: auto-detects if not provided

          // Common options
          position: 'bottom-right',
          enabled: process.env.NODE_ENV === 'development' // disable in production/hosted environments
        });

        return <YourApp />;
      }

      render(
        <LDProvider>
          <App />
        </LDProvider>,
        document.getElementById('root'),
      );
    })();
    ```
  </CodeBlock>
</CodeBlock>

### Install using a CDN

If you are not using React as your front-end framework, or want to use the developer toolbar in a way where it is decoupled from your tech stack and its dependencies, you can also instantiate the toolbar using a CDN.

To do so, add this script to your `index.html` file:

<CodeBlock>
  <CodeBlock title="index.html script">
    ```html
    <script src="https://unpkg.com/@launchdarkly/toolbar@latest/cdn/toolbar.min.js"></script>
    ```
  </CodeBlock>
</CodeBlock>

This attaches `LaunchDarklyToolbar` to your `window` and exposes an `init()` method using `window.LaunchDarklyToolbar.init()` that will lazily load the developer toolbar in the same way the React hook does.

In your corresponding code, wherever you instantiate your LaunchDarkly JavaScript client, pass in the following plugins:

<CodeBlock>
  <CodeBlock title="Pass plugins to the client">
    ```js
    import * as LDClient from 'launchdarkly-js-client-sdk';
    import { FlagOverridePlugin, EventInterceptionPlugin } from '@launchdarkly/toolbar';

    // Pass these plugins into both the JS client and 
    // the window.LaunchDarklyToolbar.init() call.
    const flagOverridePlugin = new FlagOverridePlugin();
    const eventInterceptionPlugin = new EventInterceptionPlugin();

    const context: LDClient.LDContext = {
      kind: 'user',
      key: 'context-key-123abc',
    };

    const client = LDClient.initialize('client-side-id-123abc', context, {
      plugins: [
        flagOverridePlugin,
        eventInterceptionPlugin,
        // other plugins...
      ],
      // other options...
    });

    try {
      await client.waitForInitialization(5);
      // initialization succeeded, flag values are now available
      handleInitializedClient(client);
    } catch (err) {
      // initialization failed or did not complete before timeout
    }

    // Only initialize the toolbar in local environments
    if (process.env.NODE_ENV === 'development' && window.LaunchDarklyToolbar) {
      window.LaunchDarklyToolbar.init({
        flagOverridePlugin,
        eventInterceptionPlugin,
        // other toolbar options...
      });
    }
    ```
  </CodeBlock>
</CodeBlock>

If you are using TypeScript and want type-safety for the `window.LaunchDarklyToolbar.init` call, you can add a `window.d.ts` file to the root of your web application with the following:

<CodeBlock>
  <CodeBlock title="Add a window.d.ts file">
    ```ts
    import type { LaunchDarklyToolbar } from '@launchdarkly/toolbar';

    declare global {
      interface Window {
        LaunchDarklyToolbar?: LaunchDarklyToolbar;
      }
    }
    ```
  </CodeBlock>
</CodeBlock>

## Mode options

The developer toolbar supports running in two different modes:

* **SDK mode**: Integrates with your LaunchDarkly SDK for local flag overrides and testing
* **Dev server mode**: Connects to a LaunchDarkly CLI dev server for flag browsing and real-time updates

SDK mode is the default mode for the toolbar. The toolbar switches to dev server mode only if you provide `devServerUrl`. Generally, we recommend SDK mode.

### Available features by mode

<table class="fern-table">
  <tr>
    <th>
      Mode
    </th>

    <th>
      Options
    </th>
  </tr>

  <tr>
    <td>
      SDK mode
    </td>

    <td>
      Flag overrides (if you provide `flagOverridePlugin`)<br />
      Events (if you provide `eventInterceptionPlugin`)<br />
      Settings
    </td>
  </tr>

  <tr>
    <td>
      Dev server mode
    </td>

    <td>
      Flags<br />
      Settings
    </td>
  </tr>
</table>

### Set up SDK mode

SDK mode integrates directly with your LaunchDarkly client, allowing you to:

* Override flag values locally without affecting other members
* Test different flag variations instantly
* Work offline or with any LaunchDarkly environment

Setup requires the following steps:

1. Create a `FlagOverridePlugin` instance
2. (Optional) Create an `EventInterceptionPlugin` instance
3. Pass the plugin into your LaunchDarkly SDK's plugins array
4. Pass the same plugin instance into the `LaunchDarklyToolbar` component
5. Wrap your app with the `LDProvider`

Here's how to set up SDK mode:

<CodeBlock>
  <CodeBlock title="SDK mode setup">
    ```tsx
    import { useEffect, useState } from 'react';
    import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
    import { 
      LaunchDarklyToolbar,
      FlagOverridePlugin,
      EventInterceptionPlugin 
    } from '@launchdarkly/toolbar';

    // Create the plugin instances
    const flagOverridePlugin = new FlagOverridePlugin({
      storageNamespace: 'my-app-overrides', // Optional: customize storage key
    });
    const eventInterceptionPlugin = new EventInterceptionPlugin({
      eventCapacity: 250, // Maximum events to store (default: 150)
      enableLogging: true, // Console logging for debugging (default: false)
    });

    function App() {
      const [LDProvider, setLDProvider] = useState(null);

      useEffect(() => {
        const initializeLD = async () => {
          const Provider = await asyncWithLDProvider({
            clientSideID: 'enter-your-client-side-id',
            context: { key: 'context-key-123abc', name: 'Sandy Smith' },
            options: {
              // Pass the plugins to the SDK
              plugins: [flagOverridePlugin, eventInterceptionPlugin],
            },
          });
          setLDProvider(() => Provider);
        };

        initializeLD();
      }, []);

      if (!LDProvider) {
        return <div>Loading LaunchDarkly...</div>;
      }

      return (
        <LDProvider>
          <div>
            <h1>My App</h1>
            {/* Pass the same plugin instances to the toolbar */}
            <LaunchDarklyToolbar
              flagOverridePlugin={flagOverridePlugin}
              eventInterceptionPlugin={eventInterceptionPlugin}
            />
          </div>
        </LDProvider>
      );
    }
    ```
  </CodeBlock>
</CodeBlock>

### Set up dev server mode

If your team uses the LaunchDarkly CLI dev server, start it with CORS enabled:

<CodeBlock>
  <CodeBlock title="Dev server with CORS enabled">
    ```bash
    ldcli dev-server start --project your-project --cors-enabled true
    ```
  </CodeBlock>
</CodeBlock>

Then connect the toolbar by passing in the URL of the CLI dev server:

<CodeBlock>
  <CodeBlock title="Connect the toolbar">
    ```tsx
    import { LaunchDarklyToolbar } from '@launchdarkly/toolbar';

    function App() {
      return (
        <div>
          <h1>My App</h1>
          <LaunchDarklyToolbar devServerUrl="http://localhost:8765" />
        </div>
      );
    }
    ```
  </CodeBlock>
</CodeBlock>

## Properties

You can set the following properties to personalize the toolbar.

### Flag override plugin

The flag override plugin enables flag overrides and testing:

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `flagOverridePlugin`
    </td>

    <td>
      `IFlagOverridePlugin`
    </td>

    <td>
      `undefined`
    </td>
  </tr>
</table>

### Event interception plugin

The event interception plugin enables **Events** tab functionality:

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `eventInterceptionPlugin`
    </td>

    <td>
      `IEventInterceptionPlugin`
    </td>

    <td>
      `undefined`
    </td>
  </tr>
</table>

### Base LaunchDarkly URL

You can use the base LaunchDarkly URL for link generation, such as to create a missing feature flag:

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `baseUrl`
    </td>

    <td>
      `string`

       (optional)
    </td>

    <td>
      `https://app.launchdarkly.com`
    </td>
  </tr>
</table>

### LaunchDarkly dev server URL

You can use the URL of your LaunchDarkly dev server to enable [dev server mode](#set-up-dev-server-mode):

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `devServerUrl`
    </td>

    <td>
      `string`

       (optional)
    </td>

    <td>
      `undefined`
    </td>
  </tr>
</table>

### Toolbar position

You can set the toolbar position on your screen:

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `position`
    </td>

    <td>
      `"left" | "right"`
    </td>

    <td>
      `right`
    </td>
  </tr>
</table>

### Project key

You can use a project key in multi-project setups (dev server mode only):

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `projectKey`
    </td>

    <td>
      `string`

       (optional)
    </td>

    <td>
      `undefined`
    </td>
  </tr>
</table>

### Polling interval

You can set the polling interval for dev server updates (dev server mode only):

<table class="fern-table">
  <tr>
    <th>
      Prop
    </th>

    <th>
      Type
    </th>

    <th>
      Default
    </th>
  </tr>

  <tr>
    <td>
      `pollIntervalInMs`
    </td>

    <td>
      `number`

       (optional)
    </td>

    <td>
      `5000`
    </td>
  </tr>
</table>

## Visibility control

The toolbar provides a global API for show/hide control:

<CodeBlock>
  <CodeBlock title="Visibility control">
    ```js
    // Toggle visibility
    window.ldToolbar.toggle();

    // Enable/disable explicitly
    window.ldToolbar.enable();
    window.ldToolbar.disable();

    // Check current status
    window.ldToolbar.status(); // returns true/false
    ```
  </CodeBlock>
</CodeBlock>