This is an optional React wrapper for the LaunchDarkly SDK for browser JavaScript SDK. It builds upon the JavaScript SDK, supporting all of the same functionality, but using React's Context API to provide additional conveniences:
- Easy initialization and usage with React.
- Feature flags as camelCased props.
- Subscription to flag changes out of the box.
For a general overview of JavaScript SDK characteristics, see the main README. Also see the online React SDK Reference.
This SDK needs React >= 16.3.0 because it uses the Context API.
yarn add ldclient-react
-
Call the
withLDProvider
function with your clientSideID and then pass the resulting function your root React component:import { withLDProvider } from 'ldclient-react'; const App = () => <div> <Home /> </div>; export default withLDProvider({ clientSideID: 'your-client-side-id' })(App);
-
Anywhere you need flags, call the
withLDConsumer
function and then pass your component to the resulting function. Your flags are available via props.flags:import { withLDConsumer } from 'ldclient-react'; // flags are available via props const Home = ({ flags }) => { return flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>; }; export default withLDConsumer()(Home);
withLDProvider(config: { clientSideID: string, user?: LDUser, options?: LDOptions, flags?: LDFlagSet })
withLDProvider
is a function which accepts a config object which is used to initialise ldclient-js.
It returns a function which accepts your root react component and returns a HOC. This HOC does three things:
-
It initializes the ldClient instance by calling the
initialize
method of ldclient-js oncomponentDidMount
-
It saves all flags and the ldClient instance in the Context API
-
It subscribes to flag changes and propagate them through the Context API
This is the clientSideID specific to your project and environment. You can find this in under account settings in your LD portal. This is the only property required to use the React SDK.
This user will be used to initialize the SDK. For more info about users, check here. If not specified, ldclient-react will create a default user that looks like this:
const defaultUser = {
key: uuid.v4(), // random guid
};
These options will be used to customise the ldClient instance. To see what options are available, check the JS SDK reference. For example:
withLDProvider({
clientSideID,
options: {
bootstrap: 'localStorage',
},
})(App);
You can explicitly specify the flags available to your app by setting this property. This is a flat key value object where key is the feature flag key (as shown on your LaunchDarkly dashboard, not the camelCased version) and value is the default value of the flag. Under the hood, the React SDK calls ldClient.variation on each flag you specify here. If unspecified, the React SDK will call ldClient.allFlags which is equivalent to calling variation on all the flags exposed to the JS SDK.
Explicitly specifying flags might give you better usage statistics than calling allFlags. However you will need to maintain
this list when you are adding new flags or removing old ones. For example, the code below makes dev-test-flag
and another-flag
available to your app and subscribes to them. All other flags are ignored.
withLDProvider({
clientSideID,
flags: {
'dev-test-flag': false,
'another-flag': false,
},
})(App);
The return of withLDProvider
is a function that takes your root React component and returns a HOC
with flags and ldClient saved in the Context API.
import React from 'react';
import { withLDProvider } from 'ldclient-react';
import Home from './home';
const App = () => (
<div>
<Home />
</div>
);
export default withLDProvider({
clientSideID: 'your-client-side-id',
user: { key: 'some-user-key' }, // optional
options: { bootstrap: 'localStorage' }, // optional
})(App);
withLDConsumer
is a function which accepts an optional options object. It returns a function which
accepts your component and returns a HOC injected with flags and ldClient props.
Use withLDConsumer
anywhere you need flags and ldClient. Your flags will
be available as camelCased properties under this.props.flags
and ldClient as this.props.ldClient
.
If your component only needs the ldClient instance but not flags, set this to true
. By default this
is false
meaning your component will get both flags and the ldClient instance.
The return of withLDConsumer
is a function that takes your component and returns a HOC with
flags and the ldClient instance injected via props.
import React, { Component } from 'react';
import { withLDConsumer } from 'ldclient-react';
class Home extends Component {
// track goals
onAddToCart = () => this.props.ldClient.track('add to cart');
// change user context
onLoginSuccessful = () => this.props.ldClient.identify({ key: 'someUserId' });
render() {
// access your flags through this.props.flags
return <div>{this.props.flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>}</div>;
}
}
export default withLDConsumer()(Home);
Check the example for a fully working spa with react and react-router. Remember to enter your clientSideID in the client root app file and create a flag called dev-test-flag
in your dashboard before running the example.
Third-party developers have created their own React interfaces for the LaunchDarkly JavaScript SDK:
- TrueCar/react-launch-darkly: A basic React wrapper with similar functionality
- yusinto/ld-redux: An implementation specifically for Redux
- tdeekens/flopflip: A flexible feature-toggling library that integrates with LaunchDarkly