A framework-agnostic developer toolbar for interacting with LaunchDarkly during development
npm install @launchdarkly/toolbarA framework-agnostic developer toolbar that provides real-time feature flag management and debugging capabilities during development. The toolbar integrates seamlessly with LaunchDarkly, allowing developers to inspect, override, and test feature flags without leaving their application.
- šÆ Dual Mode Operation: Works with both LaunchDarkly Dev Server and SDK
- š Real-time Flag Management: View and toggle feature flags instantly
- šØ Shadow DOM Isolation: Zero CSS conflicts with your application
- š Built-in Authentication: Secure toolbar access with LaunchDarkly authentication
- š Flexible Positioning: Place toolbar in any corner of your screen
- š Plugin System: Extend functionality with custom plugins
- š Event Monitoring: Track and inspect LaunchDarkly events
- š Search & Filter: Quickly find flags in large projects
- ā Flag Starring: Mark important flags for quick access
- ā” Hot Reload Support: Automatically reflects flag changes
``bash`
npm install @launchdarkly/toolbaror
pnpm add @launchdarkly/toolbaror
yarn add @launchdarkly/toolbar
The Developer Toolbar is intended for use during local development. As such, you should ensure that the way you are
instantiating it will keep it disabled in production environments.
The Developer Toolbar depends on your LaunchDarkly JS client having a reference to the same FlagOverridePlugin andEventInterceptionPlugin that you pass into the Developer Toolbar. As such, ensure that you instantiate the Developer Toolbar at the same time or immediately after the LaunchDarkly JS client is instantiated.useLaunchDarklyToolbar
Below are a few examples on how to instantiate the toolbar, one using the react hook, and one using the CDN hosted toolbar script.
`tsx
import { render } from 'react-dom';
import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
import { useLaunchDarklyToolbar, FlagOverridePlugin, EventInterceptionPlugin } from '@launchdarkly/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',
});
return
}
render(
document.getElementById('root'),
);
})();
`
Works with any JavaScript framework (Vue, Angular, Svelte, vanilla JS, etc.). Add this script to your index.html file.
`html`
In your corresponding code, wherever you instantiate your LaunchDarkly JS client, be sure to pass in the following plugins:
`typescript
import * as LDClient from 'launchdarkly-js-client-sdk';
import { FlagOverridePlugin, EventInterceptionPlugin } from '@launchdarkly/toolbar';
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: [
// any other plugins you might want
flagOverridePlugin,
eventInterceptionPlugin,
],
});
try {
await client.waitForInitialization(5);
// initialization succeeded, flag values are now available
handleInitializedClient(client);
} catch (err) {
// initialization failed or did not complete before timeout
}
if (process.env.NODE_ENV === 'development' && window.LaunchDarklyToolbar) {
window.LaunchDarklyToolbar.init({
flagOverridePlugin,
eventInterceptionPlugin,
position: 'bottom-right',
});
}
`
Note: if you are using typescript and want type safety for the window.LaunchDarklyToolbar.init call,window.d.ts
you can add a file to your application with the following:
`typescript
import type { LaunchDarklyToolbar } from '@launchdarkly/toolbar';
declare global {
interface Window {
LaunchDarklyToolbar?: LaunchDarklyToolbar;
}
}
`
``
@launchdarkly/toolbar/
āāā src/
ā āāā core/ # Framework-agnostic toolbar implementation
ā ā āāā context/ # React context providers
ā ā āāā services/ # Business logic (DevServerClient, FlagStateManager)
ā ā āāā ui/ # UI components (Toolbar, Tabs, List, etc.)
ā ā āāā tests/ # Unit tests
ā ā āāā index.ts # Core entry point (for CDN builds)
ā āāā react/ # React-specific integrations and utilities
ā ā āāā useLaunchDarklyToolbar.ts # Main React hook
ā ā āāā lazyLoadToolbar.ts # Dynamic CDN loading
ā āāā types/ # TypeScript type definitions
ā ā āāā config.ts # Configuration types
ā ā āāā events.ts # Event types
ā ā āāā plugins.ts # Plugin interfaces
ā ā āāā index.ts # Type exports
ā āāā index.ts # Main entry point (NPM package)
āāā dist/ # NPM package output
ā āāā index.js # ES module build
ā āāā index.cjs # CommonJS build
ā āāā index.d.ts # TypeScript definitions
āāā cdn/ # CDN bundle output
ā āāā toolbar.min.js # IIFE bundle for script tags
āāā .storybook/ # Storybook configuration
āāā stories/ # Component documentation
`typescript
interface ToolbarConfig {
// LaunchDarkly configuration
baseUrl?: string; // LaunchDarkly API base URL
projectKey?: string; // Project key (auto-detected if not provided)
// Dev Server Mode
devServerUrl?: string; // URL to LaunchDarkly dev server
// SDK Mode Plugins
flagOverridePlugin?: IFlagOverridePlugin; // Enable flag overrides
eventInterceptionPlugin?: IEventInterceptionPlugin; // Monitor events
// UI Configuration
position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
pollIntervalInMs?: number; // Polling interval (default: 1000ms)
}
`
`typescript`
interface UseLaunchDarklyToolbarConfig extends ToolbarConfig {
toolbarBundleUrl?: string; // Custom CDN URL for local development
enabled?: boolean; // Toggle toolbar on/off (default: true)
}
Connect directly to a LaunchDarkly dev server to manage server-side flags:
`tsx`
useLaunchDarklyToolbar({
devServerUrl: 'http://localhost:5764',
projectKey: 'my-project', // Optional
position: 'bottom-right',
});
or if you are using the CDN script:
`typescript`
window.LaunchDarklyToolbar.init({
devServerUrl: 'http://localhost:8080',
projectKey: 'my-project', // Optional
position: 'bottom-right',
});
Features:
- View all flags from your LaunchDarkly project
- Set flag overrides that persist in dev server
- Changes visible to all connected clients
- Ideal for backend/full-stack development
Integrate with LaunchDarkly React SDK for client-side flag management:
`tsx
import { useFlagOverridePlugin, useEventInterceptionPlugin } from './plugins';
useLaunchDarklyToolbar({
flagOverridePlugin: useFlagOverridePlugin(),
eventInterceptionPlugin: useEventInterceptionPlugin(),
position: 'bottom-right',
});
`
or if you are using the CDN script:
`typescript`
window.LaunchDarklyToolbar.init({
flagOverridePlugin: new FlagOverridePlugin(),
eventInterceptionPlugin: new EventInterceptionPlugin(),
position: 'bottom-right',
});
Features:
- Local flag overrides (client-side only)
- Event monitoring and inspection
- No dev server required
- Ideal for frontend development
`typescript`
interface IFlagOverridePlugin {
getAllFlags(): Record
setOverride(flagKey: string, value: any): void;
clearOverride(flagKey: string): void;
clearAllOverrides(): void;
onFlagsChange(callback: (flags: Record
}
`typescript`
interface IEventInterceptionPlugin {
getEvents(): ProcessedEvent[];
clearEvents(): void;
onEvent(callback: (event: ProcessedEvent) => void): () => void;
}
`bashBuild both NPM and CDN outputs
pnpm build
$3
`bash
Run unit tests
pnpm testRun tests in watch mode
pnpm test:watch
`$3
`bash
Start Storybook dev server
pnpm storybookBuild Storybook for deployment
pnpm build:storybook
``- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
Apache-2.0
- Documentation
- GitHub Repository
- npm Package
- Issue Tracker