diff --git a/.babelrc b/.babelrc
index c3dbeea..5fa716b 100644
--- a/.babelrc
+++ b/.babelrc
@@ -1,8 +1,15 @@
{
"presets": [
- "react",
- "es2015",
- "stage-0",
- "flow"
- ]
+ [
+ "@babel/preset-env",
+ {
+ "targets": {
+ "node": "current"
+ }
+ }
+ ],
+ "@babel/preset-react",
+ "@babel/preset-flow"
+ ],
+ "plugins": ["@babel/plugin-syntax-export-default-from"]
}
diff --git a/.eslintrc b/.eslintrc
index 4b2da92..9c2dd34 100644
--- a/.eslintrc
+++ b/.eslintrc
@@ -21,7 +21,14 @@
"react/prop-types": [0],
"eol-last": 2,
- "indent": [2, 2, {"SwitchCase": 1, "VariableDeclarator": { "var": 2, "let": 2, "const": 3}}],
+ "indent": [
+ 2,
+ 2,
+ {
+ "SwitchCase": 1,
+ "VariableDeclarator": { "var": 2, "let": 2, "const": 3 }
+ }
+ ],
"jsx-quotes": [2, "prefer-double"],
"linebreak-style": [2, "unix"],
"no-trailing-spaces": 1,
@@ -34,29 +41,29 @@
"react/display-name": 0,
"react/jsx-wrap-multilines": 2,
- "flowtype/define-flow-type": 1
+ "flowtype/define-flow-type": 1,
+
+ "react-hooks/rules-of-hooks": "error",
+ "react-hooks/exhaustive-deps": "warn",
+
+ "jest/no-disabled-tests": "warn",
+ "jest/no-focused-tests": "error",
+ "jest/no-identical-title": "error",
+ "jest/prefer-to-have-length": "warn",
+ "jest/valid-expect": "error"
},
"env": {
"es6": true,
"node": true,
- "browser": true
- },
- "extends": [
- "eslint:recommended",
- "plugin:react/recommended",
- ],
- "ecmaFeatures": {
- "jsx": true,
- "experimentalObjectRestSpread": true
+ "browser": true,
+ "jest/globals": true
},
- "plugins": [
- "react",
- "flowtype"
- ],
- "globals": {
- "before": true,
- "context": true,
- "describe": true,
- "it": true
+ "extends": ["eslint:recommended", "plugin:react/recommended"],
+ "plugins": ["jest", "flowtype", "react", "react-hooks"],
+ "settings": {
+ "react": {
+ "version": "detect",
+ "flowVersion": "0.93.0"
+ }
}
}
diff --git a/README.md b/README.md
index 4332ab4..8b93da6 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,39 @@
# React-Launch-Darkly
-*Simple component helpers to support LaunchDarkly in your react app.*
+
+_Simple component helpers to support LaunchDarkly in your react app._
[](https://www.npmjs.com/package/react-launch-darkly)
[](https://travis-ci.org/TrueCar/react-launch-darkly)
## Installation
+
`npm install --save react-launch-darkly`
## Dependencies
-- React `v16.3.0` or greater
- - If you use an older version of React, you can continue to use [version 1.4.0](https://github.com/TrueCar/react-launch-darkly/releases/tag/v1.4.0) of this library. However, we will no longer be actively maintaining version 1.x.
-- [LaunchDarkly client](https://docs.launchdarkly.com/docs/js-sdk-reference) / `ldclient-js`
- - `ldclient-js` needs to be a dependency within the app using `react-launch-darkly`
- - supported versions of `ldclient-js`: `^1.1.12 || ^2.0.0`
+
+- React `v16.8.0` or greater
+- [LaunchDarkly client](https://docs.launchdarkly.com/docs/js-sdk-reference) / `launchdarkly-js-client-sdk`
+ - `launchdarkly-js-client-sdk` needs to be a dependency within the app using `react-launch-darkly`
+ - supported versions of `launchdarkly-js-client-sdk`: `^2.15.1`
## Basic Usage
+
To setup the `LaunchDarkly` component wrapper, you'll probably want to include it in a top-level
layout component:
+
```javascript
// MasterLayout.js
import React, { Component } from "react";
import { LaunchDarkly } from "react-launch-darkly";
export default class MasterLayout extends Component {
- render () {
+ render() {
return (
-
+
{this.props.children}
@@ -36,13 +43,14 @@ export default class MasterLayout extends Component {
```
Then in your lower-level components, to make use of the `FeatureFlag` component:
+
```javascript
// Home.js
import React, { Component } from "react";
import { FeatureFlag } from "react-launch-darkly";
export default class Home extends Component {
- render () {
+ render() {
return (
- );
+ _renderFeature() {
+ return Your new feature!
;
}
}
```
## Docs
+
- [LaunchDarkly component](https://github.com/TrueCar/react-launch-darkly#launchdarkly-component)
- [FeatureFlag component](https://github.com/TrueCar/react-launch-darkly#featureflag-component)
- [SSR Support](https://github.com/TrueCar/react-launch-darkly#ssr-support)
@@ -71,36 +78,53 @@ export default class Home extends Component {
---
### `LaunchDarkly` component
-Main component that initializes the [LaunchDarkly js-client](https://github.com/launchdarkly/js-client).
+
+Main component that provides configuration data to `FeatureFlag` and `useFlags()`.
#### props
##### `clientId` : `string` (required)
+
This is the client id that is provided to you by LaunchDarkly.
##### `user` : `object` (required)
+
See the [LaunchDarkly docs](http://docs.launchdarkly.com/docs/js-sdk-reference#section-users) for more info.
##### `clientOptions` : `object` (optional)
Options that are passed to the LaunchDarkly JS client for additional configuration and features:
+
- [Bootstrapping](https://docs.launchdarkly.com/docs/js-sdk-reference#section-bootstrapping)
- [Secure Mode](https://docs.launchdarkly.com/docs/js-sdk-reference#section-secure-mode)
- [Setting LaunchDarkly Enterprise URLs](https://github.com/launchdarkly/js-client/blob/master/src/index.js#L241-L243)
+##### `controlTest` : `(flagValue: FlagValueType) => boolean` (optional)
+
+Control test function which is used by `useFlags` to determine whether control should be rendered. If none is provided, a default is used which checks if value starts with "control"
+
+##### `challengerTest` : `(flagValue: FlagValueType) => boolean` (optional)
+
+Challenger test function which is used by `useFlags` to determine whether challenger should be rendered. If none is provided, a default is used which checks if value does not start with "control"
+
---
### `FeatureFlag` component
+
+Component that initializes the [LaunchDarkly js-client](https://github.com/launchdarkly/js-client).
Note that this component has to be rendered as a child of `LaunchDarkly`
#### props
##### `flagKey` : `string` (required)
+
The `flagKey` prop is the feature flag key you defined in LaunchDarkly.
##### `renderFeatureCallback` : `function` (required)
+
The main callback function that renders your feature. In typical scenarios where your flag is a boolean,
you can simply create your function to return the necessary JSX:
+
```javascript
// Example FeatureFlag component
@@ -112,8 +136,81 @@ _renderFeature () {
```
##### Multivariate Flag Support
+
+When using a multivariate feature flag, the `renderFeatureCallback` prop will pass the value of
+the flag as an argument to your callback function:
+
+```javascript
+// Example FeatureFlag component
+
+
+// Callback function with feature flag value passed in
+_renderFeature (featureFlagValue) {
+ if (featureFlagValue === "A") {
+ return (Bucket "A" Feature!
);
+ }
+
+ return (Default Bucket Feature Here!
);
+}
+```
+
+#### `initialRenderCallback` : `function` (optional)
+
+Since the feature flags are requested from LaunchDarkly after DOM load, there may be some latency in the rendering. This render callback allows you to provide some sort of feedback to indicate loading, e.g., the typical spinning loader.
+
+#### `renderDefaultCallback` : `function` (optional)
+
+This callback is provided for cases where you want to render something by default, think of it when your feature flag is "off" or falsy.
+
+---
+
+### `useFlags` hook
+
+Hook that initializes the [LaunchDarkly js-client](https://github.com/launchdarkly/js-client).
+Note that any component using `useFlags` has to be rendered as a child of `LaunchDarkly`
+
+#### arguments
+
+##### `flagKey` : `string` (required)
+
+The `flagKey` prop is the feature flag key you defined in LaunchDarkly.
+
+#### return
+
+##### `matchControl` : `() => boolean`
+
+Helper which can be used to determine whether flag has a control value. `matchControl` internally uses `controlTest` to determine if flag has a control value.
+
+##### `matchChallenger` : `() => boolean`
+
+Helper which can be used to determine whether flag has a challenger value. `matchChallenger` internally uses `challengerTest` to determine if flag has a challenger value.
+
+##### `match` : `(value: string) => boolean`
+
+Helper which can be used to determine whether flag has a specific value.
+
+```javascript
+// Example usage
+const TestComponent = (props = {}) => {
+ const { matchControl, matchChallenger, match } = useFlags("my-flag");
+ return (
+
+ {matchControl() &&
Matched any control
}
+ {matchChallenger() &&
Matched any challenger
}
+ {match("challenger2") && (
+
Matched a specific challenger – challenger 2
+ )}
+
Matched nothing
+
"initial rendered"
);
+ .mockReturnValue(initial rendered
);
mount(
{
- const renderFeatureCallback = jest.fn().mockImplementation((flagValue) => {
- if(flagValue === {a: 1}) {return "feature object 1"
;}
- if(flagValue === 1) {return "feature number 1"
;}
- if(flagValue === [1]) {return "feature array 1"
;}
- return (
- "feature rendered"
- );
+ const renderFeatureCallback = jest.fn().mockImplementation(flagValue => {
+ if (flagValue === { a: 1 }) {
+ return feature object 1
;
+ }
+ if (flagValue === 1) {
+ return feature number 1
;
+ }
+ if (flagValue === [1]) {
+ return feature array 1
;
+ }
+ return feature rendered
;
});
- const renderDefaultCallback = jest.fn().mockReturnValue("default rendered"
);
- const initialRenderCallback = jest.fn().mockReturnValue("initial rendered"
);
+ const renderDefaultCallback = jest
+ .fn()
+ .mockReturnValue(default rendered
);
+ const initialRenderCallback = jest
+ .fn()
+ .mockReturnValue(initial rendered
);
const variation = jest.fn();
const ldClientWrapperOn = jest.fn();
- const ldClientWrapperOnReady = jest.fn((callback) => {
+ const ldClientWrapperOnReady = jest.fn(callback => {
callback();
});
- const shallowRender = (options) => (
+ const shallowRender = options =>
shallow(
{
user={{}}
clientId="123"
{...options}
- />,{ disableLifecycleMethods: true }
- )
- );
- const mountRender = (options) => (
+ />,
+ { disableLifecycleMethods: true }
+ );
+ const mountRender = options =>
mount(
{
renderFeatureCallback={renderFeatureCallback}
{...options}
/>
- )
- );
+ );
beforeEach(() => {
utils.ldClientWrapper = jest.fn();
@@ -62,10 +69,13 @@ describe("components/FeatureFlagRenderer", () => {
describe("when instantiated", () => {
it("sets the state", () => {
const wrapper = shallowRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: false, flagValue: false });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: false,
+ flagValue: false
+ });
});
- describe ("when bootstrap has flag key and value", () => {
+ describe("when bootstrap has flag key and value", () => {
it("sets the state", () => {
const clientOptions = {
bootstrap: {
@@ -73,14 +83,19 @@ describe("components/FeatureFlagRenderer", () => {
}
};
const wrapper = shallowRender({ clientOptions });
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: false, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: false,
+ flagValue: true
+ });
});
});
});
describe("when rendered", () => {
it("renders the proper data-qa attribute", () => {
- expect(shallowRender().find("[data-qa='FeatureFlag-my-test']")).toBeDefined();
+ expect(
+ shallowRender().find("[data-qa='FeatureFlag-my-test']")
+ ).toBeDefined();
});
describe("when flagValue is true", () => {
@@ -95,7 +110,9 @@ describe("components/FeatureFlagRenderer", () => {
it("renders the feature callback for that object", () => {
const wrapper = shallowRender();
wrapper.setState({ flagValue: { a: 1 } });
- expect(wrapper.text()).toEqual(renderFeatureCallback({ a: 1 }).props.children);
+ expect(wrapper.text()).toEqual(
+ renderFeatureCallback({ a: 1 }).props.children
+ );
});
});
@@ -111,7 +128,9 @@ describe("components/FeatureFlagRenderer", () => {
it("renders the feature callback for that array", () => {
const wrapper = shallowRender();
wrapper.setState({ flagValue: [1] });
- expect(wrapper.text()).toEqual(renderFeatureCallback([1]).props.children);
+ expect(wrapper.text()).toEqual(
+ renderFeatureCallback([1]).props.children
+ );
});
});
@@ -120,15 +139,23 @@ describe("components/FeatureFlagRenderer", () => {
describe("when renderDefaultCallback is provided", () => {
it("renders the default callback", () => {
const wrapper = shallowRender({ renderDefaultCallback });
- wrapper.setState({ flagValue: false, checkFeatureFlagComplete: true });
- expect(wrapper.text()).toEqual(renderDefaultCallback().props.children);
+ wrapper.setState({
+ flagValue: false,
+ checkFeatureFlagComplete: true
+ });
+ expect(wrapper.text()).toEqual(
+ renderDefaultCallback().props.children
+ );
});
});
describe("when renderDefaultCallback is not provided", () => {
it("renders nothing", () => {
const wrapper = shallowRender();
- wrapper.setState({ flagValue: false, checkFeatureFlagComplete: true });
+ wrapper.setState({
+ flagValue: false,
+ checkFeatureFlagComplete: true
+ });
wrapper.setProps({ renderDefaultCallback: null });
expect(wrapper.text()).toEqual("");
});
@@ -139,15 +166,23 @@ describe("components/FeatureFlagRenderer", () => {
describe("when initialRenderCallback is provided", () => {
it("renders the initial callback", () => {
const wrapper = shallowRender({ initialRenderCallback });
- wrapper.setState({ flagValue: false, checkFeatureFlagComplete: false });
- expect(wrapper.text()).toEqual(initialRenderCallback().props.children);
+ wrapper.setState({
+ flagValue: false,
+ checkFeatureFlagComplete: false
+ });
+ expect(wrapper.text()).toEqual(
+ initialRenderCallback().props.children
+ );
});
});
describe("when initialRenderCallback is not provided", () => {
it("renders nothing", () => {
const wrapper = shallowRender();
- wrapper.setState({ flagValue: false, checkFeatureFlagComplete: false });
+ wrapper.setState({
+ flagValue: false,
+ checkFeatureFlagComplete: false
+ });
wrapper.setProps({ initialRenderCallback: null });
expect(wrapper.text()).toEqual("");
});
@@ -159,7 +194,10 @@ describe("components/FeatureFlagRenderer", () => {
it("it renders nothing", () => {
const wrapper = shallowRender();
wrapper.setState({ flagValue: false, checkFeatureFlagComplete: false });
- wrapper.setProps({ renderDefaultCallback: null, initialRenderCallback: null });
+ wrapper.setProps({
+ renderDefaultCallback: null,
+ initialRenderCallback: null
+ });
expect(wrapper.type()).toEqual(null);
});
});
@@ -200,7 +238,11 @@ describe("components/FeatureFlagRenderer", () => {
};
mountRender({ ...config });
- expect(utils.ldClientWrapper).toHaveBeenCalledWith(config.clientId, config.user, config.clientOptions);
+ expect(utils.ldClientWrapper).toHaveBeenCalledWith(
+ config.clientId,
+ config.user,
+ config.clientOptions
+ );
});
describe("when change event emits", () => {
@@ -221,12 +263,18 @@ describe("components/FeatureFlagRenderer", () => {
});
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: true
+ });
expect(callbackSpy).not.toHaveBeenCalled();
jest.runAllTimers();
expect(callbackSpy).toHaveBeenCalled();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: expectedFlagValue });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: expectedFlagValue
+ });
});
});
@@ -234,7 +282,10 @@ describe("components/FeatureFlagRenderer", () => {
it("sets the state", () => {
variation.mockImplementation(() => true);
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: true
+ });
});
});
@@ -242,42 +293,67 @@ describe("components/FeatureFlagRenderer", () => {
it("sets the state", () => {
variation.mockImplementation(() => false);
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: false });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: false
+ });
});
});
describe("query param flag overrides if not undefined", () => {
it("param 'features.flag=false' overrides LD data 'on'", () => {
variation.mockImplementation(() => false);
- utils.getLocation = jest.fn().mockImplementation(() => "http://ab.cdef.com?features.my-test=false");
+ utils.getLocation = jest
+ .fn()
+ .mockImplementation(
+ () => "http://ab.cdef.com?features.my-test=false"
+ );
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: false });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: false
+ });
});
it("param 'features.flag' overrides LD data 'off'", () => {
variation.mockImplementation(() => false);
- utils.getLocation = jest.fn().mockImplementation(() => "http://ab.cdef.com?features.my-test");
+ utils.getLocation = jest
+ .fn()
+ .mockImplementation(() => "http://ab.cdef.com?features.my-test");
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: true
+ });
});
it("param 'features=flag' overrides LD data 'off'", () => {
variation.mockImplementation(() => false);
- utils.getLocation = jest.fn().mockImplementation(() => "http://ab.cdef.com?features=my-test");
+ utils.getLocation = jest
+ .fn()
+ .mockImplementation(() => "http://ab.cdef.com?features=my-test");
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: true
+ });
});
it("param comma-list of features to enable", () => {
- variation.mockImplementation((flagKey) => {
- if(flagKey === "one" || flagKey === "my-test") {
+ variation.mockImplementation(flagKey => {
+ if (flagKey === "one" || flagKey === "my-test") {
return false;
}
return true;
});
- utils.getLocation = jest.fn().mockImplementation(() => "http://ab.cdef.com?features=one,my-test");
+ utils.getLocation = jest
+ .fn()
+ .mockImplementation(() => "http://ab.cdef.com?features=one,my-test");
const wrapper = mountRender();
- expect(wrapper.state()).toEqual({ checkFeatureFlagComplete: true, flagValue: true });
+ expect(wrapper.state()).toEqual({
+ checkFeatureFlagComplete: true,
+ flagValue: true
+ });
});
});
});
diff --git a/test/components/LaunchDarkly.test.js b/test/components/LaunchDarkly.test.js
index aa2237f..a94852a 100644
--- a/test/components/LaunchDarkly.test.js
+++ b/test/components/LaunchDarkly.test.js
@@ -1,6 +1,7 @@
import React from "react";
import { configure, shallow } from "enzyme";
import LaunchDarkly from "../../src/components/LaunchDarkly";
+import { defaultControlTest, defaultChallengerTest } from "../../src/lib/utils";
const Adapter = require("enzyme-adapter-react-16");
configure({ adapter: new Adapter() });
@@ -11,13 +12,22 @@ describe("components/LaunchDarkly", () => {
clientId: "12345",
user: {
key: "user123"
- }
+ },
+ clientOptions: void 0,
+ controlTest: defaultControlTest,
+ challengerTest: defaultChallengerTest
};
const provider = shallow(
-
- Hi
- );
- expect(provider.find("ContextProvider").props().value).toEqual(expectedConfig);
+
+ Hi
+
+ );
+ expect(provider.find("ContextProvider").props().value).toEqual(
+ expectedConfig
+ );
});
describe("when clientOptions is available", () => {
@@ -29,7 +39,9 @@ describe("components/LaunchDarkly", () => {
},
clientOptions: {
baseUrl: "http://test"
- }
+ },
+ controlTest: defaultControlTest,
+ challengerTest: defaultChallengerTest
};
const provider = shallow(
{
describe("when either clientId or user are missing", () => {
it("broadcasts null", () => {
// with neither
- let provider = shallow(Hi
);
+ let provider = shallow(
+
+ Hi
+
+ );
expect(provider.props().value).toEqual(null);
// with clientId
- provider = shallow(Hi
);
+ provider = shallow(
+
+ Hi
+
+ );
expect(provider.props().value).toEqual(null);
// with user
- provider = shallow(Hi
);
+ provider = shallow(
+
+ Hi
+
+ );
expect(provider.props().value).toEqual(null);
});
});
diff --git a/test/hooks/useFlags.test.js b/test/hooks/useFlags.test.js
new file mode 100644
index 0000000..1c2628a
--- /dev/null
+++ b/test/hooks/useFlags.test.js
@@ -0,0 +1,123 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import LaunchDarkly from "../../src/components/LaunchDarkly";
+import useFlags from "../../src/hooks/useFlags";
+import * as LDClient from "launchdarkly-js-client-sdk";
+
+LDClient.initialize = jest.fn(() => ({
+ identify: () => new Promise([]),
+ variation: () => "",
+ on: () => {},
+ track: () => {},
+ allFlags: () => ({})
+}));
+
+describe("hooks/useFlags", () => {
+ const flagKey = "abc";
+ const generateConfig = bootstrap => {
+ const config = {
+ clientId: "80808080",
+ user: {
+ key: "abc123"
+ },
+ clientOptions: {
+ baseUrl: "https://test"
+ }
+ };
+ if (bootstrap) {
+ config.clientOptions.bootstrap = bootstrap;
+ }
+ return config;
+ };
+
+ const TestComponent = (props = {}) => {
+ const { matchControl, matchChallenger, match } = useFlags(
+ props.flagKey || ""
+ );
+ return (
+
+ {matchControl() &&
Matched control
}
+ {matchChallenger() &&
Matched challenger
}
+ {match("challenger2") &&
Matched challenger 2
}
+
Matched nothing
+