Test flags with the developer toolbar
Inspect the flags your app is using, try local on/off outcomes and change the evaluation context while you build. The toolbar is a testing surface, not a second console.
- Time
- About 6 min
- Who can do it
- A developer testing a client-side integration
- Where
- Your local React, Next.js, Vue, plain JavaScript or React Native app
- You finish with
- A reproducible way to test flag states without editing the remote environment
What it does#
The FlagSwift developer toolbar wraps the normal React provider and gives you a small in-app control surface. It can:
- List the flags loaded by the current client.
- Force a flag on or off for the current client instance.
- Restore the server value or reset every override.
- Try another user, account or device context.
- Refresh flags and see loading or connection errors.
- Search the flag list, and show only the flags you have overridden.
- Remember whether it was open and which tab you were on while the browser tab lives.
It ships with the React, Next.js, Vue, plain JavaScript and React Native SDKs. Server SDKs and native mobile SDKs have no screen to draw on, so they use the override methods shown below instead.
Local only
React setup#
Install the React SDK
bash npm install @flagswift/reactRender it inside FlagProvider
tsx import { DeveloperToolbar, FlagClient, FlagProvider } from "@flagswift/react"; const client = new FlagClient({ apiKey: import.meta.env.VITE_FLAGSWIFT_CLIENT_KEY, baseUrl: import.meta.env.VITE_FLAGSWIFT_URL, environment: "development", }); export function Providers({ children }) { return ( <FlagProvider client={client}> {children} <DeveloperToolbar /> </FlagProvider> ); }Try a flag
Open the FlagSwift launcher, search for a flag and pick
On,OfforServerin its switch. UseLocal onlyto review your overrides, and theContexttab to try another user. The existing hooks re-render because the override is part of the client's local state.
Production guard#
<DeveloperToolbar enabled={import.meta.env.DEV} />The component defaults to hidden when NODE_ENV is production. An explicit build-time condition is still recommended for applications that use a custom bundler.
How the toolbar behaves#
- A small FlagSwift button sits in the corner. It shows a dot for the connection (green ready, amber loading, red error) and a count of local overrides.
- Opening it shows the Flags tab: each flag with its status (On, Off or Kill switch), its variant, and a Server / On / Off switch. Flags you have overridden carry a Local badge and are listed first.
- Local only narrows the list to your overrides. It is disabled until you have one. Reset all in the footer clears every override.
- The footer tells you what just happened (for example, “checkout forced on locally”) and shows connection errors.
- A flag with its kill switch active cannot be forced on or off. Its switch is disabled and a note explains that the kill switch wins.
- Escape closes the panel. In the browser, open or closed and the active tab are kept in session storage, so they survive a reload and are forgotten when the tab closes.
- In production builds nothing renders, and no code runs.
| Option | Description |
|---|---|
| enabled | Show the toolbar. Defaults to on outside production builds (NODE_ENV for the web SDKs, __DEV__ in React Native). |
| position | bottom-right (default), bottom-left, top-right or top-left. |
| defaultOpen | Start expanded instead of as a button. A saved open or closed state from earlier in the session wins. |
| title | The panel heading. Default: FlagSwift Dev Tools. |
| theme | auto (follows the visitor's light or dark scheme, default), light or dark. |
Vue, plain JavaScript and React Native#
Vue#
Render the component anywhere under the installed plugin. It draws into the page body, so it does not affect your layout.
<script setup lang="ts">
import { DeveloperToolbar } from "@flagswift/vue";
</script>
<template>
<RouterView />
<DeveloperToolbar :enabled="import.meta.env.DEV" />
</template>Plain JavaScript#
Any framework, or none. mountDeveloperToolbar returns a handle with open(), close() and destroy(). It does nothing during server rendering.
import { FlagSwift, mountDeveloperToolbar } from "@flagswift/js";
const flags = FlagSwift.init({ apiKey: "fs_client_...", baseUrl: "https://flags.example.com" });
const toolbar = mountDeveloperToolbar(flags, { enabled: import.meta.env.DEV, position: "bottom-left" });
// when you tear the page down
toolbar.destroy();React Native#
The React Native build draws with native views and follows the device colour scheme. It shows only in debug builds (__DEV__), and keeps its open state in memory because there is no session storage. Render it once, high in the tree, inside the provider.
import { DeveloperToolbar, FlagSwiftProvider } from "@flagswift/react-native";
export default function App() {
return (
<FlagSwiftProvider client={client}>
<Navigation />
<DeveloperToolbar position="bottom-left" />
</FlagSwiftProvider>
);
}Next.js setup#
Use the client entry point. The server entry can still use the same override methods in local tests, but the visual toolbar must render in a client component.
"use client";
import { DeveloperToolbar, FlagSwiftProvider } from "@flagswift/nextjs/client";
export function Providers({ children, initialFlags }) {
return (
<FlagSwiftProvider
config={{ apiKey: process.env.NEXT_PUBLIC_FLAGSWIFT_KEY!, baseUrl: process.env.NEXT_PUBLIC_FLAGSWIFT_URL! }}
initialFlags={initialFlags}
>
{children}
<DeveloperToolbar position="bottom-right" />
</FlagSwiftProvider>
);
}Custom tooling without the UI#
Every TypeScript SDK built on @flagswift/core exposes the same runtime methods. This is useful for automated browser tests or a product-specific debug panel.
client.setOverride("new-checkout", true);
client.getOverrides();
client.clearOverride("new-checkout");
client.clearOverrides();| Method | Description |
|---|---|
| setOverride(key, true | { enabled, variant, value }) | Applies a local result to the client instance. |
| getOverrides() | Returns a copy of the active local overrides. |
| clearOverride(key) | Restores one flag to its server result. |
| clearOverrides() | Restores every flag to its server result. |
Kill switches win
isKillSwitchEnabled continues to report the server state.What to check#
- The toolbar lists flags after the client has loaded or from initial flags.
- Setting a flag On or Off changes useFlag, useFlagValue and useVariant consumers immediately (in Vue, the matching composables and FlagFeature).
- Reloading the page keeps the panel open on the same tab, and closing the browser tab forgets it.
- A flag with an active kill switch cannot be forced.
- Server value removes the local override without changing the Enterprise flag.
- Changing the evaluation context triggers a normal client re-evaluation.
- A production build does not render the toolbar.
Related#
- React SDKProvider, hooks, component and client methods.
- Next.js SDKServer evaluation and the no-flicker client provider.
- Vue SDKPlugin, composables and the toolbar component.
- JavaScript SDKThe framework-free client and mountDeveloperToolbar.
- React Native SDKProvider, hooks and the native toolbar.
- SDK featuresCompare behavior across SDKs.