@useboolean/boolean-react

Boolean

Feature management for modern devops teams by Boolean.

npm i @useboolean/boolean-react

---

Features

• Percentage-based rollout
• User targeting & segmentation
• Turn off features instantly
• Privacy-first
• Audit log
• SSO / SAML

⚠️ Create an account at Boolean. There is a free plan available.

---

Quick start

Use the useBoolean(..) hook to easily get the value of your feature flag.

function MyComponent() {
  const { isEnabled } = useBoolean(`my-feature`);

  if (isEnabled) {
    // Return you enhanced feature.
  }

  // Return your regular feature.
}

And add the BooleanProvider in the root of your component tree (so the hooks receive the data via the new context api).

⚠️ Copy the api key from the Boolean site under the API Keys menu item.

<BooleanProvider apiKey={process.env.BOOLEAN_API_KEY}>
  {/* Your component tree here */}
</BooleanProvider>

Important

• We use the WebSocket api. Configure a polyfill if you're targeting older browsers. https://www.caniuse.com/#search=websocket
• If WebSockets are not available, or the connection cannot be established, we use the standard fetch API to make networks requests. It's not supported in all browsers yet. Use a polyfill if you wish to support these browsers (and you're not polyfilling this yet). If you do not configure a polyfill, the library will not fall back to http requests.
• In addition, this library also uses the standard AbortController which may also require a polyfill.
• The client optionally caches data using localforage. If possible, unlike plain localStorage, localforage does async storage to avoid blocking the main render loop. If localforage is not available the client does not cache data.

📄 Seeing logs? Don't worry. The client library logs errors and warnings only when NODE_ENV is not set to production.

Subjects & Advanced Targetting

You can optionally pass a subjectId and/or subjectData to the useBoolean(..) hook. These properties are used to determine which feature flags are enabled for the current subject by looking at the configured percentage on the different segments.

⚠️ A subjectId may be the currently signed in user id. But it could also be a project's id or group of user ids. Two users chatting with eachother or colleague's working in the same project probably want to see the same features.

function MyComponent({ user }) {
  const { isEnabled } = useBoolean(`my-feature`, user.id, {
    email: user.email,
  });

  if (isEnabled) {
    // Return you enhanced feature.
  }

  // Return your regular feature.
}

⚠️ If you configured a percentage on your feature flag, you must pass in a subjectId or the feature flag will be disabled by default. You can always generate and store a random subjectId for anonymous users.

In Boolean's admin panel you can manage your segments. For example: create an Internal Users segment with a rule email ENDS_WITH @useboolean.com. When your feature flag includes this segment it will only be enabled to internal users.

Pass more properties so you have more targetting options in your segments: days since acquisition; time zone; network connection; profile data; etc.

The segments and their rules are evaluated locally: so Boolean does not consume your users' data. This is by design to protect the privacy of your users.

Initial Data

When BooleanProvider mounts, it immediately loads Boolean's data. But it's possible to call useBoolean() before any data is loaded. By default, features will be turned off if no data has been loaded yet. There are several methods to avoid this.

The first and prefered method is to specify the initial data when building your app. The initial data will be used as fallback when no data has been loaded yet.

curl https://booleanapi.com/data?api_key=$BOOLEAN_API_KEY > initialData.json

⚠️ Make sure to set your BOOLEAN_API_KEY.

Now, you can simply import the initialData.json and pass it to BooleanProvider. By importing your data, it's immediately bundled with your code making sure there is always a set of data available.

<BooleanProvider apiKey={process.env.BOOLEAN_API_KEY} initialData={initialData}>
  {/* your component tree here */}
</BooleanProvider>

Alternatively, you can check the isLoading state of Boolean. For returning visitors, it's advised to cache previous data so it's available immediately. To enable caching, simply install the localforage module.

Below an example to check the loading state of my-feature and enable the feature if data is still loading.

function MyComponent() {
  const { isLoading, isEnabled } = useBoolean(`my-feature`);

  if (isLoading || isEnabled) {
    // Return you enhanced feature.
  }

  // Return your regular feature.
}

📨 If you have any feedback or just want to say hi you can send us a ping. Over & out!