README.md

ld-react

This package has been superseded by the official LaunchDarkly React SDK. Please use that instead.

The quickest and easiest way to integrate launch darkly with react 🎉

Why this package?

• Easy and fast to use. Two steps to get feature flags into your react app.
• Supports subscription out of the box. You get live changes on the client as you toggle features.
• You automatically get camelCased keys as opposed to the default kebab-cased.
• No need for redux! This package uses the new context api which is available from react ^16.3.0.

Dependency

This needs react ^16.4.0! It won't work otherwise.

Installation

yarn add ld-react

Quickstart

1. Wrap your root app withFlagProvider:

   import {withFlagProvider} from 'ld-react';
   
   const App = () =>
     <div>
       <Home />
    </div>;
   
   export default withFlagProvider(App, {clientSideId: 'your-client-side-id'});

2. Wrap your component withFlags to get them via props:

   import {withFlags} from 'ld-react';
   
   const Home = props => {
      // flags are available via props.flags
      return props.flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>;
   };
   
   export default withFlags(Home);

That's it!

API

withFlagProvider(Component, {clientSideId, user, options})

This is a hoc which accepts a component and a config object with the above properties. Component and clientSideId are mandatory.

For example:

import {withFlagProvider} from 'ld-react';

const App = () =>
  <div>
    <Home />
 </div>;

export default withFlagProvider(App, {clientSideId: 'your-client-side-id'});

The user property is optional. You can initialise the sdk with a custom user by specifying one. This must be an object containing at least a "key" property. If you don't specify a user object, ld-react will create a default one that looks like this:

const defaultUser = {
  key: uuid.v4(), // random guid
  ip: ip.address(),
  custom: {
    browser: userAgentParser.getResult().browser.name,
    device
  }
};

For more info on the user object, see here.

The options property is optional. It can be used to pass in extra options such as Bootstrapping. For example:

withFlagProvider(Component, {
    clientSideId,
    options: {
      bootstrap: 'localStorage',
    },
});

withFlags(Component)

This is a hoc which passes all your flags to the specified component via props. Your flags will be available as camelCased properties under this.props.flags. For example:

import {withFlags} from 'ld-react';

class Home extends Component {
  render() {
    return (
      <div>
        {
          this.props.flags.devTestFlag ? // Look ma, feature flag!
            <div>Flag on</div>
            :
            <div>Flag off</div>
        }
      </div>
    );
  }
}

export default withFlags(Home);

ldClient

Internally the ld-react initialises the ldclient-js sdk and stores a reference to the resultant ldClient object in memory. You can use this object to access the official sdk methods directly. For example, you can do things like:

import {ldClient} from 'ld-react';

class Home extends Component {
 
  // track goals
  onAddToCard = () => ldClient.track('add to cart'); 
 
  // change user context
  onLoginSuccessful = () => ldClient.identify({key: 'someUserId'});
  
  // ... other implementation
}

For more info on changing user context, see the official documentation.

Example

Check the example for a fully working spa with react and react-router. Remember to enter your client side sdk in the client root app file and create a test flag called dev-test-flag before running the example!