Skip to content
Daniel Gietmann
← Blog
Coding

Toggling feature flags in React without them getting stuck

localflag toggles feature flags in React in a type-safe way and right in the browser, with its own panel. Where toggled flags get stuck, what useFeatureFlag really checks, and why none of it is secret.

Some features are finished enough to merge but not yet finished enough for everyone, for example a new checkout or a setting that only a few people should test first. That is what feature flags are for: the code is already in the build, but it is only shown once the flag is on.

For React projects I built localflag. The package is small, the flags are type-safe, and in the bundled panel you toggle them right in the browser. It does not need a server for that.

Creating flags

npm install @localflag/react

The package requires React version 18 or later. The flags live in one place, with as const, so that TypeScript knows the names and values:

// flags.ts
export const defaultFlags = {
  newCheckout: false,
  newHeader: true,
  maxItems: 10,
  apiVersion: "v1",
} as const;

export type AppFlags = typeof defaultFlags;

If you want a short explanation for each flag, use createFlags. It returns the flags and the descriptions separately. If you pass the descriptions to the provider through descriptions, the panel shows them next to the switches.

Then the provider goes around the app:

import { FeatureFlagProvider, LocalFlagDevTools } from "@localflag/react";
import { defaultFlags, type AppFlags } from "./flags";

export function App() {
  return (
    <FeatureFlagProvider<AppFlags> defaultFlags={defaultFlags}>
      <Shop />
      <LocalFlagDevTools />
    </FeatureFlagProvider>
  );
}

In the components you query the flags with hooks, or you use the FeatureFlag component with a fallback:

<FeatureFlag<AppFlags> flag="newCheckout" fallback={<OldCheckout />}>
  <NewCheckout />
</FeatureFlag>

If you mistype the name, TypeScript complains, because flag only accepts the keys from AppFlags.

The panel

LocalFlagDevTools puts a floating panel over the page. There you toggle flags without touching the code, and that way you test both states of a page one after the other without rebuilding.

Opening and closing it also works with Cmd+Shift+F, on Windows and Linux with Ctrl+Shift+F. With shortcut={false} you switch the shortcut off. You can enter a different combination there as a string, but in version 0.0.6 localflag does not evaluate it and keeps reacting to Cmd/Ctrl+Shift+F.

You set the corner with position or in the panel under "Options". localflag already saves the current corner on the first load under localflag:position in localStorage, and from then on this value wins against the prop. So if you change position in the code later, the panel stays where it was before in your browser.

Toggled flags get stuck

What you toggle in the panel ends up as an override in localStorage, under the key localflag:overrides. That is intentional: after a reload the flag is still set the way you set it. The README does give feature-flags as the default, but the code uses localflag:overrides. So that is the key you look for when you check in the browser.

The overrides always win against the default values. If you later change newCheckout to true in the code, you still keep seeing false in your browser if you had switched the flag off there once. It then looks as if the change had not arrived. resetFlags() from useFeatureFlagControls or the "Reset overrides" button in the panel deletes all overrides. With storageKey you give each app its own key, so that two projects on localhost do not change each other's flags.

useFeatureFlag only asks whether a value is truthy

Flags can be booleans, strings or numbers. But useFeatureFlag always returns a boolean, namely the result of Boolean(wert). For maxItems: 10 that means true, for 0 it means false. A string "false" is true as well, because it is not empty.

So for everything that is not a real switch, use useFeatureFlagValue:

const maxItems = useFeatureFlagValue<AppFlags>("maxItems");
const apiVersion = useFeatureFlagValue<AppFlags>("apiVersion");

Everything happens in the browser

The default values are in the shipped JavaScript, the overrides in the visitor's localStorage. The panel only hides itself when a global variable __DEV__ is set to false, and Vite, for example, does not set that on its own. So if you render <LocalFlagDevTools /> in the production build, your visitors see it too.

So only include the panel in development, and only persist the overrides there too. In a Vite project that looks like this:

<FeatureFlagProvider<AppFlags>
  defaultFlags={defaultFlags}
  persistOverrides={import.meta.env.DEV}
>
  <Shop />
  {import.meta.env.DEV && <LocalFlagDevTools />}
</FeatureFlagProvider>

A flag still cannot be hidden completely this way. The default values and the code behind the flag are in the bundle, and anyone who opens the browser's developer tools finds both. To hide something half-finished, that is enough. Whatever really has to stay secret has no place in client code.

Next.js and server rendering

The package contains no "use client" directive. In the Next.js App Router you therefore put the provider into its own file that starts with "use client", and include that file in the layout.

With server rendering there is also no localStorage. So the server always renders with the default values. If there are overrides in the browser, the client starts with different values. If the output depends on such a flag, the HTML from the server does not match the first render in the browser, and React reports a hydration error. For pages that are rendered on the server, you are therefore better off setting persistOverrides to false and toggling flags there only through the default values.

What it is a good fit for

localflag is a tool for development and for small projects where a flag in the code is enough. You merge a half-finished feature behind a flag, switch it on and off locally, and change the default value when it is finished. After that the flag can come out again. If flags should apply to specific users or be toggled without a new deployment, you need a service with a server behind it.

Common questions

Why does my feature flag not change even though I changed the default value in the code?
With localflag, everything you toggle in the panel ends up as an override in localStorage under localflag:overrides, and the overrides always win against the default values. resetFlags() from useFeatureFlagControls or the "Reset overrides" button in the panel deletes all overrides.
What is the difference between useFeatureFlag and useFeatureFlagValue?
useFeatureFlag from localflag always returns a boolean, namely the result of Boolean(wert). A number like 10 or the string "false" therefore result in true. For everything that is not a real switch, you use useFeatureFlagValue instead.
Do visitors see the localflag panel in the production build?
Yes, if you render LocalFlagDevTools in the production build. The panel only hides itself when a global variable __DEV__ is set to false, and Vite, for example, does not set that on its own. So only include the panel in development.
What do I need to watch out for with localflag, Next.js and server rendering?
The localflag package contains no "use client" directive, so in the Next.js App Router you put the provider into its own file that starts with "use client". The server always renders with the default values, so overrides in the browser can lead to a hydration error. For pages that are rendered on the server, you are better off setting persistOverrides to false.