React feature flags and remote configuration

Featurevisor comes with an additional package for React.js, for ease of integration in your React.js application for evaluating features (including their flags, variations and variables).

Installation#

Install with npm:

$ npm install @featurevisor/react @featurevisor/sdk

Setting up the provider#

Use FeaturevisorProvider component to set up the SDK instance in your React application:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { createFeaturevisor } from '@featurevisor/sdk'
import { FeaturevisorProvider } from '@featurevisor/react'
const DATAFILE_URL = '...'
const response = await fetch(DATAFILE_URL)
if (!response.ok) {
  throw new Error(`Could not fetch datafile: HTTP ${response.status}`)
}
const f = createFeaturevisor({
  datafile: await response.json(),
  context: { userId: '123' },
})
const rootElement = document.getElementById('root')
if (!rootElement) {
  throw new Error('Root element not found')
}
createRoot(rootElement).render(
  <StrictMode>
    <FeaturevisorProvider instance={f}>
      <App />
    </FeaturevisorProvider>
  </StrictMode>,
)

React hooks#

The package comes with several hooks to use in your components:

useFeaturevisor#

To access the bound methods coming from the underlying JavaScript SDK instance:

import React from 'react'
import { useFeaturevisor } from '@featurevisor/react'
function MyComponent(props) {
  const {
    isEnabled,
    getVariation,
    getVariable,
    getVariableBoolean,
    getVariableString,
    getVariableInteger,
    getVariableDouble,
    getVariableArray,
    getVariableObject,
    getVariableJSON,
    setContext,
    getContext,
    setStickyFeatures,
    setStickyVariables,
  } = useFeaturevisor()
  return <p>...</p>
}

Learn more about the API from original JavaScript SDK documentation.

The functions returned from the hook will not trigger any re-renders of the component if the datafile or context changes at the instance level.

The ones below are reactive.

useFlag#

Check if a feature is enabled or not:

import React from 'react'
import { useFlag } from '@featurevisor/react'
function MyComponent(props) {
  const isEnabled = useFlag('myFeatureKey')
  if (isEnabled) {
    return <p>Feature is enabled</p>
  }
  return <p>Feature is disabled</p>
}

useVariation#

Get a feature's evaluated variation:

import React from 'react'
import { useVariation } from '@featurevisor/react'
function MyComponent(props) {
  const variation = useVariation('myFeatureKey')
  if (variation === 'b') {
    return <p>B variation</p>;
  }
  if (variation === 'c') {
    return <p>C variation</p>;
  }
  // default
  return <p>Default experience</p>;
};

TypeScript users can optionally narrow the result to the expected variation values:

type CheckoutVariation = 'control' | 'treatment'
const variation = useVariation<CheckoutVariation>('checkout')
// CheckoutVariation | null

Without the generic, existing usage continues to return string | null.

useVariable#

Get a feature's evaluated variable value:

import React from 'react'
import { useVariable } from '@featurevisor/react'
function MyComponent(props) {
  const colorValue = useVariable('myFeatureKey', 'color')
  return <p>Color: {colorValue}</p>;
};

TypeScript users can optionally provide the expected variable type:

interface CheckoutConfig {
  title: string
  maxItems: number
}
const config = useVariable<CheckoutConfig>('checkout', 'config')
// CheckoutConfig | null

Without the generic, existing usage continues to return the general VariableValue | null type. Generic types are compile time expectations and do not validate values at runtime. Use code generation when you want project aware feature keys, variable keys, variation values, and variable types.

Use the overloaded useVariable(variableKey, context) signature to evaluate a global variable with a variable key and optional context:

const email = useVariable<string>('supportEmail', { country: 'nl' })

useSdk#

If you want to access the full Featurevisor SDK instance:

import React from 'react'
import { useSdk } from '@featurevisor/react'
function MyComponent(props) {
  const f = useSdk()
  return <p>...</p>
}

Passing additional context#

All the evaluation hooks accept an optional argument for passing additional component-level context:

const context = {
  // ... additional context here in component
}
useFlag(featureKey, context)
useVariation(featureKey, context)
useVariable(featureKey, variableKey, context)
useVariable(globalVariableKey, context)

Reactivity#

All the evaluation hooks are reactive. This means that your components will automatically re-render when:

a newer datafile is set
context is set or updated
sticky features are set or updated
sticky global variables are set or updated

Datafile updates identify the affected feature and global variable keys. This includes indirect changes caused by updated segments and transitive required feature dependencies. Hooks ignore unrelated datafile changes, then compare the previous and new evaluated values before rendering the component again.

If you do not want any reactivity, you are better off using the Featurevisor SDK instance directly in your component either via useSdk or useFeaturevisor hooks.

Optimization#

Given the nature of components in React, they can re-render many times.

You are advised to minimize the number of calls to Featurevisor SDK in your components by using memoization techniques.

Example repository#

You can find a fully functional example of a React application using Featurevisor SDK here: https://github.com/featurevisor/featurevisor-example-react.