Skip to content
FlagSwiftDocs

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

Overrides never call the Enterprise mutation APIs and are not visible to other users. Keep the toolbar disabled in production builds, and never use it as an operational kill switch.

React setup#

  1. Install the React SDK

    bash
    npm install @flagswift/react
  2. Render 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>
      );
    }
  3. Try a flag

    Open the FlagSwift launcher, search for a flag and pick On, Off or Server in its switch. Use Local only to review your overrides, and the Context tab to try another user. The existing hooks re-render because the override is part of the client's local state.

Production guard#

tsx
<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.
Toolbar options
OptionDescription
enabledShow the toolbar. Defaults to on outside production builds (NODE_ENV for the web SDKs, __DEV__ in React Native).
positionbottom-right (default), bottom-left, top-right or top-left.
defaultOpenStart expanded instead of as a button. A saved open or closed state from earlier in the session wins.
titleThe panel heading. Default: FlagSwift Dev Tools.
themeauto (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.

html
<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.

ts
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.

tsx
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.

tsx
"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.

ts
client.setOverride("new-checkout", true);
client.getOverrides();
client.clearOverride("new-checkout");
client.clearOverrides();
Runtime override methods
MethodDescription
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

A configured kill switch remains authoritative. Forcing a kill-switched flag on still evaluates it as off, while 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.