npm package: @ff00ff/boolean-react
Description: Boolean's react client library to make it easy to start using feature flags
Author: Boolean
Latest version: 0.7.0

# 🎚 Boolean

[![Build Status](https://travis-ci.org/Ff00ff/boolean-react.svg?branch=master)](https://travis-ci.org/Ff00ff/boolean-react)
[![Coverage Status](https://coveralls.io/repos/Ff00ff/boolean-react/badge.svg?branch=master&service=github)](https://coveralls.io/github/Ff00ff/boolean-react?branch=master)
[![License Badge](https://img.shields.io/github/license/Ff00ff/boolean-react.svg)](https://github.com/Ff00ff/boolean-react/blob/master/LICENSE)

Feature management for modern devops teams by [Boolean](https://useboolean.com/).

```
npm i @ff00ff/boolean-react
```

---

### Features

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

> ⚠️ Create an account at [Boolean](https://useboolean.com/). We have different plans available for different teams including a free trial.

---

<br/>

## Quick start

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

```jsx
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](https://useboolean.com/) under the API Keys menu item.

```jsx
<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](https://caniuse.com/#feat=fetch). 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`.

<br/>

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

```jsx
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](https://useboolean.com/) 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.

## Loading

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. As soon as data will be available the feature will be flipped accordingly.

To change this behaviour 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.

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

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

  // Return your regular feature.
}
```

<br/>

> 📨 If you have any feedback or just want to say hi you can [send us a ping](mailto:support@useboolean.com). Over & out!