Merge pull request #3149 from spotify/rugvip/ff

core-api: refactor and slim down the FeatureFlagsApi

docs/reference/createPlugin-feature-flags.md

@@ -8,12 +8,6 @@ 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
@@ -21,8 +15,7 @@ import { createPlugin } from '@backstage/core';
 
 export default createPlugin({
   id: 'welcome',
-  register({ router, featureFlags }) {
-    // router.registerRoute('/', Component);
+  register({ featureFlags }) {
     featureFlags.register('enable-example-feature');
   },
 });
@@ -30,41 +23,22 @@ export default createPlugin({
 
 ## 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, new FeatureFlags());
-
-export default builder.build() as ApiHolder;
-```
-
-Then, later, you can directly use it via `useApi`:
+To inspect the state of a feature flag inside your plugin, you can use the
+`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example:
 
 ```tsx
 import React, { FC } from 'react';
 import { Button } from '@material-ui/core';
-import { FeatureFlagState, featureFlagsApiRef, useApi } from '@backstage/core';
+import { featureFlagsApiRef, useApi } from '@backstage/core';
 
-const ExampleButton: FC<{}> = () => {
-  const flags = useApi(featureFlagsApiRef).getFlags();
-
-  const handleClick = () => {
-    flags.set('enable-example-feature', FeatureFlagState.On);
-  };
+const ExamplePage = () => {
+  const featureFlags = useApi(featureFlagsApiRef);
 
   return (
-    <Button variant="contained" color="primary" onClick={handleClick}>
-      Enable the 'enable-example-feature' feature flag
-    </Button>
+    <div>
+      <MyPluginWidget>
+      { featureFlags.isActive('enable-example-feature') && <ExperimentalPluginWidget> }
+    </div>
   );
 };
 ```