Skip to content

Commit

Permalink
Updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@yusinto
yusinto committed Jan 18, 2018
1 parent 3af6e69 commit df3b0f5
Showing 1 changed file with 36 additions and 61 deletions.
97 changes: 36 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,27 +13,34 @@ If you use react redux and you want to store your feature flags as part of your
* Camel casing your keys so you can use them in code with the dot operator. The keys by default are dash separated so you can't do this out of the box with the [official sdk](https://github.com/launchdarkly/js-client).
* Server Sent Event works as well so your app will respond live to feature flag changes without the users having to refresh the browser!

## Breaking changes in v2
ld-redux v2 is *NOT* backwards compatible! It has been re-written so the api is cleaner and much easier to use:
* No more isLDReady (thank god)
* No more ldConnect (yayy!)
* One step initialisation

## Installation

yarn add ld-redux

or the old school way

npm i --save ld-redux

## Quickstart

1. In your client bootstrap, initialise the launch darkly client by invoking initLD method:
1. In your client bootstrap, initialise the launch darkly client by invoking the init method:

```javascript
import createStore from '<your-project>/store';
import ldRedux from 'ld-redux';

// standard redux createStore
const store = createStore();
const flags = { 'feature-flag-key': false };

// Pass redux store to ld-redux so it can store flags in redux state
ldRedux.init('yourClientSideId', store);
// do this once
ldRedux.init({
clientSideId: 'your-client-side-id',
store,
flags,
});

render(
<Provider store={store}>
Expand All @@ -52,40 +59,32 @@ npm i --save ld-redux
export default combineReducers({
...reducers,
LD: ldRedux.reducer(), // Note: key must be upper case LD
LD: ldRedux.reducer(), // Note: the LD key can be anything you want
});
```

3. Subscribe to flags in your redux container:
3. Map state to props:

```javascript
import {connect} from 'react-redux';
import ldRedux, {ldConnect} from 'ld-redux';
import * as yourActions from '<your-project>/actions/yourActions';
// These must be the keys you set up in launch darkly dashboard (kebab-lower-cased)
const homeFlags = {'feature-flag-key': false};
const mapStateToProps = (state) => {
// Use getFlags to access flags from LD state
const flags = ldRedux.getFlags(state, homeFlags);
const {featureFlagKey} = state.LD; // Note: the key LD must be the same as step 2.
return {
...flags,
featureFlagKey,
};
};
// Use ldConnect to connect your component to the feature flags it needs
@connect(mapStateToProps, yourActions)
@ldConnect(homeFlags)
@connect(mapStateToProps)
export default class HomeContainer extends Component {
render() {
return <HomeComponent {...this.props} />;
}
};
```

4. Finally in your component, your feature flags are available from props in camelCase:
4. Finally in your component, your feature flags are available from props:

```javascript
import React, {Component} from 'react';
Expand All @@ -110,9 +109,11 @@ npm i --save ld-redux
```

## API
### init(clientSideId, reduxStore, customUser, options)
You can initialise the sdk with a custom user by passing it as the third argument to the init method. This must be an object containing
at least a "key" property. If you don't specify a customUser object, ldRedux will create a default one that looks like this:
### init({clientSideId, store, flags, user, options})
The init method accepts an object with the above properties. `clientSideId`, `store` and `flags` are mandatory.

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, ldRedux will create a default one that looks like this:
```javascript
const defaultUser = {
Expand All @@ -127,49 +128,23 @@ const defaultUser = {
For more info on the user object, see [here](http://docs.launchdarkly.com/docs/js-sdk-reference#section-users).
The final parameter `options` can be used to pass in extra options such as [Bootstrapping](https://github.com/launchdarkly/js-client#bootstrapping). For example:
The `options` property is optional. It can be used to pass in extra options such as [Bootstrapping](https://github.com/launchdarkly/js-client#bootstrapping).
For example:
```javascript
ldRedux.init('yourClientSideId', store, customUser, {
bootstrap: 'localStorage'
ldRedux.init({
clientSideId,
store,
flags,
options: {
bootstrap: 'localStorage',
}
});
```
### reducer()
This is ld-redux's reducer comprising of a single boolean flag isLDReady. You must include this reducer in your app
as per step 2 above with the key 'LD'. This name is referenced by the getFlags method to retrieve flags from redux state (see below).


### getFlags(reduxState, flags)
Extract the specified flags from the given redux state, using the given flag values as default. Internally this
looks for the LD key in your state tree to retrieve flags from. The flags argument must be an object like this:

```javascript
const flags = {
'feature-flag': false,
'another-feature-flag': true
};
```
The keys in this object must be the same as the one you set up in launch darkly dashboard. They will be
kebab-lower-cased. The values will be used as default values for the flags.


### @ldConnect(flags)
This decorator does the hard work of retrieving each flag variation for the given flags so the wrapped component
will be able to consume them. The flags object is the same as the one you used in getFlags method above.

It also subscribes your component to feature flag changes (implemented via sse) so it can react (no pun intended)
automatically to changes without browser refresh.

For more info on subscribing to flag changes, see [here](http://docs.launchdarkly.com/docs/js-sdk-reference#section-subscribing-to-feature-flag-changes).


### isLDReady reducer state
This is a boolean flag in LD reducer which gets set to true when the sdk has finished loading. You can subscribe to this state if you
need to perform custom operations on component load. By default, the ldRedux.getFlags method injects this flag implicitly so if you follow
step 3 above, you'll find that isLDReady is already available as props in your component.
This is ld-redux's reducer. You must include this reducer in your app as per step 2 above with any key of your choice.
You then use this key to retrieve your flags from redux's state.
### window.ldClient
Internally the ldRedux.init method above initialises the js sdk and stores the resultant ldClient object in window.ldClient. You can use
Expand Down

0 comments on commit df3b0f5

Please sign in to comment.