Merge pull request #391 from spotify/bil/feature-flags

Add Feature Flags API 🎚

docs/reference/README.md

@@ -4,5 +4,6 @@ APIs and Components
 
 - [createPlugin](createPlugin.md)
 - [createPlugin - router](createPlugin-router.md)
+- [createPlugin - feature flags](createPlugin-feature-flags.md)
 
 [Back to Docs](../README.md)

docs/reference/createPlugin-feature-flags.md

@@ -0,0 +1,65 @@
+# createPlugin - feature flags
+
+The `featureFlags` object passed to the `register` function makes it possible for plugins to register Feature Flags in Backstage for users to opt into. You can use this to split out logic in your code for manual A/B testing, etc.
+
+```typescript
+export type FeatureFlagsHooks = {
+  register(name: FeatureFlagName): void;
+};
+```
+
+Here's a code sample:
+
+```typescript
+import { createPlugin } from '@backstage/core';
+
+export default createPlugin({
+  id: 'welcome',
+  register({ router, featureFlags }) {
+    // router.registerRoute('/', Component);
+    featureFlags.register('enable-example-feature');
+  },
+});
+```
+
+## Using with useApi
+
+To use it, you'll first need to register the `FeatureFlags` API via `ApiRegistry` in your `apis.ts` in your App:
+
+```tsx
+import {
+  ApiHolder,
+  ApiRegistry,
+  featureFlagsApiRef,
+  FeatureFlags,
+} from '@backstage/core';
+
+const builder = ApiRegistry.builder();
+builder.add(featureFlagsApiRef, FeatureFlags);
+
+export default builder.build() as ApiHolder;
+```
+
+Then, later, you can directly use it via `useApi`:
+
+```tsx
+import React, { FC } from 'react';
+import { Button } from '@material-ui/core';
+import { featureFlagsApiRef, useApi } from '@backstage/core';
+
+const ExampleButton: FC<{}> = () => {
+  const flags = useApi(featureFlagsApiRef).getFlags();
+
+  const handleClick = () => {
+    flags.set('enable-example-feature', FeatureFlagState.On);
+  };
+
+  return (
+    <Button variant="contained" color="primary" onClick={handleClick}>
+      Enable the 'enable-example-feature' feature flag
+    </Button>
+  );
+};
+```
+
+[Back to References](README.md)

docs/reference/createPlugin.md

@@ -17,13 +17,14 @@ type PluginHooks = {
 };
 ```
 
-[Read more about the router here](createPlugin-router.md)
+- [Read more about the router here](createPlugin-router.md)
+- [Read more about feature flags here](createPlugin-feature-flags.md)
 
 ## Example Uses
 
 ### Creating a basic plugin
 
-Showcasing adding multiple routes and a redirect.
+Showcasing adding multiple routes, a feature flag and a redirect.
 
 ```jsx
 import { createPlugin } from '@backstage/core';
@@ -31,7 +32,9 @@ import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
   id: 'new-plugin',
-  register({ router }) {
+  register({ router, featureFlags }) {
+    featureFlags.register('enable-example-component');
+
     router.registerRoute('/new-plugin', ExampleComponent);
   },
 });