|
1 | | -# LaunchDarkly SDK for Browser JavaScript - React Wrapper |
| 1 | +# LaunchDarkly Client-side SDK for React |
2 | 2 |
|
3 | 3 | [](https://circleci.com/gh/launchdarkly/react-client-sdk/tree/master) |
4 | 4 |
|
|
8 | 8 |
|
9 | 9 | [](https://twitter.com/intent/follow?screen_name=launchdarkly) |
10 | 10 |
|
11 | | -## Introduction |
| 11 | +## Supported React versions |
12 | 12 |
|
13 | | -This is an optional React wrapper for the LaunchDarkly SDK for browser JavaScript SDK. It builds upon the [JavaScript SDK](https://github.com/launchdarkly/js-client-sdk), supporting all of the same functionality, but using React's Context API to provide additional conveniences: |
| 13 | +This version of the LaunchDarkly SDK is compatible with versions 16.3.0 and later of React because it uses React's Context API. However, if you are using the SDK's Hooks API or `asyncWithLDProvider`, then you must use React version 16.8.0 or later. |
14 | 14 |
|
15 | | -* Easy initialization and usage with React. |
16 | | -* Feature flags as camelCased props. |
17 | | -* Subscription to flag changes out of the box. |
| 15 | +Additionally, refer to the [JavaScript SDK README](https://github.com/launchdarkly/js-client-sdk#browser-compatibility) to learn more about browser compatibility. |
18 | 16 |
|
19 | | -For a general overview of JavaScript SDK characteristics, see the [JavaScript SDK](https://github.com/launchdarkly/js-client-sdk). Also see the online [React SDK Reference](https://docs.launchdarkly.com/docs/react-sdk-reference). |
| 17 | +## Getting started |
20 | 18 |
|
21 | | -## Dependency |
| 19 | +Refer to the [SDK documentation](https://docs.launchdarkly.com/docs/react-sdk-reference#section-getting-started) for instructions on getting started with using the SDK. |
22 | 20 |
|
23 | | -This SDK needs React >= 16.3.0 because it uses the Context API. |
| 21 | +Please note that the React SDK has two special requirements in terms of your LaunchDarkly environment. First, in terms of the credentials for your environment that appear on your [Account Settings](https://app.launchdarkly.com/settings/projects) dashboard, the React SDK uses the "Client-side ID"-- not the "SDK key" or the "Mobile key". Second, for any feature flag that you will be using in React code, you must check the "Make this flag available to client-side SDKs" box on that flag's Settings page. |
24 | 22 |
|
25 | | -## Installation |
| 23 | +## Learn more |
26 | 24 |
|
27 | | -``` |
28 | | -yarn add launchdarkly-react-client-sdk |
29 | | -``` |
| 25 | +Check out our [documentation](https://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](https://docs.launchdarkly.com/docs/react-sdk-reference) or our [code-generated API documentation](https://launchdarkly.github.io/react-client-sdk/). |
30 | 26 |
|
31 | | -## Quickstart |
| 27 | +This SDK builds upon the [JavaScript SDK](https://github.com/launchdarkly/js-client-sdk), supporting all of the same functionality, but using React's Context API to provide additional conveniences. While using this SDK you may need to directly interact with the underlying JavaScript SDK. For more information on how to use the JavaScript SDK and its characteristics, see the [SDK's README](https://github.com/launchdarkly/js-client-sdk/blob/master/README.md). |
32 | 28 |
|
33 | | -1. Call the `withLDProvider` function with your `clientSideID` and then pass the resulting function |
34 | | -your root React component: |
| 29 | +## Testing |
35 | 30 |
|
36 | | - ```js |
37 | | - import { withLDProvider } from 'launchdarkly-react-client-sdk'; |
38 | | - |
39 | | - const App = () => |
40 | | - <div> |
41 | | - <Home /> |
42 | | - </div>; |
43 | | - |
44 | | - export default withLDProvider({ clientSideID: 'your-client-side-id' })(App); |
45 | | - ``` |
46 | | - |
47 | | -2. Anywhere you need flags, call the `withLDConsumer` function and then pass your component |
48 | | -to the resulting function. Your flags are available via props.flags: |
49 | | - |
50 | | - ```js |
51 | | - import { withLDConsumer } from 'launchdarkly-react-client-sdk'; |
52 | | - |
53 | | - // flags are available via props |
54 | | - const Home = ({ flags }) => { |
55 | | - return flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>; |
56 | | - }; |
57 | | - |
58 | | - export default withLDConsumer()(Home); |
59 | | - ``` |
60 | | - |
61 | | -## API |
62 | | -### `withLDProvider(config: { clientSideID: string, user?: LDUser, options?: LDOptions, flags?: LDFlagSet })` |
63 | | -`withLDProvider` is a function which accepts a config object which is used to initialise launchdarkly-js-client-sdk. |
64 | | -It returns a function which accepts your root react component and returns a HOC. This HOC does three things: |
65 | | - |
66 | | -* It initializes the ldClient instance by calling the `initialize` method of launchdarkly-js-client-sdk on `componentDidMount` |
67 | | - |
68 | | -* It saves all flags and the ldClient instance in the Context API |
69 | | - |
70 | | -* It subscribes to flag changes and propagate them through the Context API |
71 | | - |
72 | | -#### Parameter |
73 | | -#### `config: { clientSideID: string, user?: LDUser, options?: LDOptions, flags?: LDFlagSet }` |
74 | | - |
75 | | -##### `clientSideID: string` |
76 | | -This is the clientSideID specific to your project and environment. You can find this in |
77 | | -under account settings in your LD portal. This is the only property required to use the |
78 | | -React SDK. |
79 | | - |
80 | | -##### `user?: LDUser` |
81 | | -This user will be used to initialize the SDK. For more info about users, check [here](http://docs.launchdarkly.com/docs/js-sdk-reference#section-users). |
82 | | -If not specified, launchdarkly-react-client-sdk will create a default user that looks like this: |
83 | | - |
84 | | - ```js |
85 | | - const defaultUser = { |
86 | | - key: uuid.v4(), // random guid |
87 | | - }; |
88 | | - ``` |
89 | | - |
90 | | -##### `options?: LDOptions` |
91 | | -These options will be used to customise the ldClient instance. To see what options are available, check the |
92 | | -[JS SDK reference](https://docs.launchdarkly.com/docs/js-sdk-reference#section-customizing-your-client). |
93 | | -For example: |
94 | | - |
95 | | - ```js |
96 | | - withLDProvider({ |
97 | | - clientSideID, |
98 | | - options: { |
99 | | - bootstrap: 'localStorage', |
100 | | - }, |
101 | | - })(App); |
102 | | - ``` |
103 | | - |
104 | | -##### `flags?: LDFlagSet` |
105 | | -You can explicitly specify the flags available to your app by setting this property. This is a flat |
106 | | -key value object where key is the feature flag key (as shown on your LaunchDarkly dashboard, not the camelCased version) |
107 | | -and value is the default value of the flag. Under the hood, the React SDK calls ldClient.variation on each flag |
108 | | -you specify here. If unspecified, the React SDK will call ldClient.allFlags which is equivalent to |
109 | | -calling variation on all the flags exposed to the JS SDK. |
110 | | - |
111 | | -Explicitly specifying flags might give you better usage statistics than calling allFlags. However you will need to maintain |
112 | | -this list when you are adding new flags or removing old ones. For example, the code below makes `dev-test-flag` |
113 | | -and `another-flag` available to your app and subscribes to them. All other flags are ignored. |
114 | | - |
115 | | - ```js |
116 | | - withLDProvider({ |
117 | | - clientSideID, |
118 | | - flags: { |
119 | | - 'dev-test-flag': false, |
120 | | - 'another-flag': false, |
121 | | - }, |
122 | | - })(App); |
123 | | - ``` |
124 | | - |
125 | | -#### Returns |
126 | | -The return of `withLDProvider` is a function that takes your root React component and returns a HOC |
127 | | -with flags and ldClient saved in the Context API. |
128 | | - |
129 | | -#### Example Usage |
130 | | -```js |
131 | | -import React from 'react'; |
132 | | -import { withLDProvider } from 'launchdarkly-react-client-sdk'; |
133 | | -import Home from './home'; |
134 | | - |
135 | | -const App = () => ( |
136 | | - <div> |
137 | | - <Home /> |
138 | | - </div> |
139 | | -); |
140 | | - |
141 | | -export default withLDProvider({ |
142 | | - clientSideID: 'your-client-side-id', |
143 | | - user: { key: 'some-user-key' }, // optional |
144 | | - options: { bootstrap: 'localStorage' }, // optional |
145 | | -})(App); |
146 | | -``` |
147 | | - |
148 | | ------------------ |
149 | | - |
150 | | -### `withLDConsumer(options?: { clientOnly: boolean })` |
151 | | -`withLDConsumer` is a function which accepts an optional options object. It returns a function which |
152 | | -accepts your component and returns a HOC injected with flags and ldClient props. |
153 | | - |
154 | | -Use `withLDConsumer` anywhere you need flags and ldClient. Your flags will |
155 | | -be available as camelCased properties under `this.props.flags` and ldClient as `this.props.ldClient`. |
156 | | - |
157 | | -#### Parameter |
158 | | -#### `options: { clientOnly: boolean } = { clientOnly: false }` |
159 | | - |
160 | | -##### `clientOnly: boolean` |
161 | | -If your component only needs the ldClient instance but not flags, set this to `true`. By default this |
162 | | -is `false` meaning your component will get both flags and the ldClient instance. |
163 | | - |
164 | | -#### Returns |
165 | | -The return of `withLDConsumer` is a function that takes your component and returns a HOC with |
166 | | -flags and the ldClient instance injected via props. |
167 | | - |
168 | | -#### Example usage: |
169 | | -```js |
170 | | -import React, { Component } from 'react'; |
171 | | -import { withLDConsumer } from 'launchdarkly-react-client-sdk'; |
172 | | - |
173 | | -class Home extends Component { |
174 | | - // track goals |
175 | | - onAddToCart = () => this.props.ldClient.track('add to cart'); |
176 | | - |
177 | | - // change user context |
178 | | - onLoginSuccessful = () => this.props.ldClient.identify({ key: 'someUserId' }); |
179 | | - |
180 | | - render() { |
181 | | - // access your flags through this.props.flags |
182 | | - return <div>{this.props.flags.devTestFlag ? <div>Flag on</div> : <div>Flag off</div>}</div>; |
183 | | - } |
184 | | -} |
185 | | - |
186 | | -export default withLDConsumer()(Home); |
187 | | - |
188 | | -``` |
189 | | - |
190 | | ------------------ |
191 | | - |
192 | | -### `useFlags()` |
193 | | -`useFlags` is a custom hook which returns all feature flags. It uses the `useContext` primitive |
194 | | -to access the LaunchDarkly context set up by `withLDProvider`. As such you will still need to |
195 | | -use the `withLDProvider` HOC at the root of your app to initialise the React SDK and populate the |
196 | | -context with the ldClient and your flags. |
197 | | - |
198 | | -#### Returns |
199 | | -Returns all the feature flags configured in your LaunchDarkly project. |
200 | | - |
201 | | -#### Example usage: |
202 | | -```js |
203 | | -import React from 'react'; |
204 | | -import { useFlags } from 'launchdarkly-react-client-sdk'; |
205 | | - |
206 | | -const HooksDemo = () => { |
207 | | - const { devTestFlag } = useFlags(); |
208 | | - |
209 | | - return ( |
210 | | - <div>{devTestFlag ? 'Flag on' : 'Flag off'}</div> |
211 | | - ); |
212 | | -}; |
213 | | - |
214 | | -export default HooksDemo; |
215 | | -``` |
216 | | - |
217 | | -### `useLDClient()` |
218 | | -`useLDClient` is a custom hook which returns the underlying [LaunchDarkly JavaScript SDK client object](https://launchdarkly.github.io/js-client-sdk/interfaces/_launchdarkly_js_client_sdk_.ldclient.html). |
219 | | -Like the `useFlags` custom hook, `useLDClient` also uses the `useContext` primitive to access the launch |
220 | | -darkly context setup by `withLDProvider`. You will still need to use the `withLDProvider` HOC |
221 | | -to initialise the react sdk to use this custom hook. |
222 | | - |
223 | | -#### Returns |
224 | | -Returns the launchdarkly-js-client-sdk object. |
225 | | - |
226 | | -#### Example usage: |
227 | | -```js |
228 | | -import React from 'react'; |
229 | | -import { useLDClient } from 'launchdarkly-react-client-sdk'; |
230 | | - |
231 | | -const HooksDemo = () => { |
232 | | - const ldClient = useLDClient(); |
233 | | - |
234 | | - // track goals |
235 | | - const onAddToCart = () => ldClient.track('add to cart'); |
236 | | - |
237 | | - // change user context |
238 | | - const onLoginSuccessful = () => ldClient.identify({ key: 'someUserId' }); |
239 | | - |
240 | | - return ( |
241 | | - <div>Hooks ldClient demo</div> |
242 | | - ); |
243 | | -}; |
244 | | - |
245 | | -export default HooksDemo; |
246 | | -``` |
247 | | - |
248 | | -## Example |
249 | | - |
250 | | -Check the [example](example) for a fully working SPA with `react` and `react-router`. Remember to enter your `clientSideID` in the client [root app file](example/src/universal/app.js) and create a flag called `dev-test-flag` in your dashboard before running the example. |
251 | | - |
252 | | -## Alternatives from the community |
253 | | - |
254 | | -Third-party developers have created their own React interfaces for the LaunchDarkly JavaScript SDK: |
255 | | - |
256 | | -* [TrueCar/react-launch-darkly](https://github.com/TrueCar/react-launch-darkly/): A basic React wrapper with similar functionality |
257 | | -* [yusinto/ld-redux](https://github.com/yusinto/ld-redux/): An implementation specifically for Redux |
258 | | -* [tdeekens/flopflip](https://github.com/tdeekens/flopflip): A flexible feature-toggling library that integrates with LaunchDarkly |
| 31 | +We run integration tests for all our SDKs using a centralized test harness. This approach gives us the ability to test for consistency across SDKs, as well as test networking behavior in a long-running application. These tests cover each method in the SDK, and verify that event sending, flag evaluation, stream reconnection, and other aspects of the SDK all behave correctly. |
259 | 32 |
|
260 | 33 | ## Contributing |
261 | 34 |
|
|
0 commit comments