From ab014e17d99bf888b4bf571316b8de7e098cb2f3 Mon Sep 17 00:00:00 2001 From: John Kilmister Date: Fri, 9 Sep 2022 20:20:22 +0100 Subject: [PATCH 1/2] Added new docs for plugin feature flags Signed-off-by: John Kilmister --- docs/plugins/feature-flags.md | 64 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 2 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 docs/plugins/feature-flags.md diff --git a/docs/plugins/feature-flags.md b/docs/plugins/feature-flags.md new file mode 100644 index 0000000000..466fdace21 --- /dev/null +++ b/docs/plugins/feature-flags.md @@ -0,0 +1,64 @@ +--- +id: feature-flags +title: Feature Flags +description: Details the process of defining setting and reading a plugin feature flag. +--- + +Backstage offers the ability to define feature flags inside a plugin. This allows you to restrict parts of your plugin to those individual users who have toggled the feature flag to on. + +This page describes the process of defining setting and reading a plugin feature flag. If you are looking for using Feature flags with software templates that can be found under [Writing Templates](https://backstage.io/docs/features/software-templates/writing-templates#remove-sections-or-fields-based-on-feature-flags). + +## Defining a Feature Flag + +Before using a feature flag we must first define it. This is done when we create the plugin by passing the name of the feature flag into the `featureFlags` array. + +```ts +/* src/plugin.ts */ +import { createPlugin, createRouteRef } from '@backstage/core-plugin-api'; +import ExampleComponent from './components/ExampleComponent'; + +export const examplePlugin = createPlugin({ + id: 'example', + routes: { + root: rootRouteRef, + }, + featureFlags: [{ name: 'show-example-feature' }], +}); +``` + +## Enabling Feature Flags + +Feature flags are defaulted to off and can be updated by individual users in the backstage interface. + +These are set by navigating to the page under `Settings` > `Feature Flags`. + +The users selection is saved in the users browsers local storage. Once toggled it may be required for a user to refresh the page to see any new changes. + +## FeatureFlagged Component + +The easiest way to control content based on the state of a feature flag is to use the [FeatureFlagged](https://backstage.io/docs/reference/core-app-api.featureflagged) component. + +```ts +import { FeatureFlagged } from '@backstage/core-app-api' + +... + + + + + + + + +``` + +## Evaluating Feature Flag State + +It is also possible to test the feature flag state using the [FeatureFlags Api](https://backstage.io/docs/reference/core-plugin-api.featureflagsapi). + +```ts +import { useApi, featureFlagsApiRef } from '@backstage/core-plugin-api'; + +const featureFlagsApi = useApi(featureFlagsApiRef); +const isOn = featureFlagsApi.isActive('show-example-feature'); +``` diff --git a/mkdocs.yml b/mkdocs.yml index 7368602298..0d386e63fa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,10 +127,10 @@ nav: - Create a Backstage Plugin: 'plugins/create-a-plugin.md' - Plugin Development: 'plugins/plugin-development.md' - Structure of a plugin: 'plugins/structure-of-a-plugin.md' - - Plugin Development: 'plugins/plugin-development.md' - Integrate into the Software Catalog: 'plugins/integrating-plugin-into-software-catalog.md' - Composability System: 'plugins/composability.md' - Plugin Analytics: 'plugins/analytics.md' + - Feature Flags: 'plugins/feature-flags.md' - Backends and APIs: - Proxying: 'plugins/proxying.md' - Backend plugin: 'plugins/backend-plugin.md' From 90aefde6d3e51c4c3b8ef7c234f77fdb913a8447 Mon Sep 17 00:00:00 2001 From: John Kilmister Date: Sat, 10 Sep 2022 12:02:48 +0100 Subject: [PATCH 2/2] Updated case on feature flag text Signed-off-by: John Kilmister --- docs/plugins/feature-flags.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/feature-flags.md b/docs/plugins/feature-flags.md index 466fdace21..a26eb49a9b 100644 --- a/docs/plugins/feature-flags.md +++ b/docs/plugins/feature-flags.md @@ -6,7 +6,7 @@ description: Details the process of defining setting and reading a plugin featur Backstage offers the ability to define feature flags inside a plugin. This allows you to restrict parts of your plugin to those individual users who have toggled the feature flag to on. -This page describes the process of defining setting and reading a plugin feature flag. If you are looking for using Feature flags with software templates that can be found under [Writing Templates](https://backstage.io/docs/features/software-templates/writing-templates#remove-sections-or-fields-based-on-feature-flags). +This page describes the process of defining setting and reading a plugin feature flag. If you are looking for using feature flags with software templates that can be found under [Writing Templates](https://backstage.io/docs/features/software-templates/writing-templates#remove-sections-or-fields-based-on-feature-flags). ## Defining a Feature Flag