diff --git a/README.md b/README.md index af94c4d..e65daa5 100644 --- a/README.md +++ b/README.md @@ -13,17 +13,19 @@ 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 '/store'; @@ -31,9 +33,14 @@ npm i --save 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( @@ -52,32 +59,24 @@ 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 '/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 ; @@ -85,7 +84,7 @@ npm i --save ld-redux }; ``` -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'; @@ -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 = { @@ -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