From 23a6cc6e6647914639371950e40d5beedba90069 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 14 Aug 2024 17:09:19 +0200
Subject: [PATCH] docs/frontend-system: fill in plugin docs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../architecture/15-plugins.md                | 82 ++++++-------------
 1 file changed, 23 insertions(+), 59 deletions(-)

diff --git a/docs/frontend-system/architecture/15-plugins.md b/docs/frontend-system/architecture/15-plugins.md
index c1539f0309..66fea76989 100644
--- a/docs/frontend-system/architecture/15-plugins.md
+++ b/docs/frontend-system/architecture/15-plugins.md
@@ -10,84 +10,48 @@ description: Frontend plugins
 
 ## Introduction
 
-<!--
+Frontend plugins are a foundational building block in Backstage and the frontend system. They are used to encapsulate and provide functionality for a Backstage app, such as new pages, navigational elements, APIs, as well as extensions and features for other plugins, such entity page cards and content for the Software Catalog, or result list items for the search plugin.
 
-Introduce frontend plugins and how each of them is shipped as a separate package. Highlight that each package should only export a single plugin instance.
-
--->
+Each plugin is typically shipped in a separate NPM package, whether that's a published package, or just in the local workspace. The plugins instance should always the `default` export of the package, either via the main entry-point or the `/alpha` sub-path export. Each plugin package is limited to exporting a single plugin instance. In a local workspace you could use a different structure if preferred, but this is considered a non-standard layout and should be avoided in published packages.
 
 ## Creating a Plugin
 
-<!--
-
-How to create a simple plugin
-
- -->
+Frontend plugin instances are created with the `createFrontendPlugin` function, which is provided by the `@backstage/frontend-plugin-api` package. It takes a single options object that provides all of the necessary configuration for the plugin. In particular you will want to provide [extensions](./20-extensions.md) for your plugin, as that is the way that you can provide new functionality to the app.
 
 ```ts
-export const myPlugin = createFrontendPlugin({
+// This creates a new extension, see "Extension Blueprints" documentation for more details
+const myPage = PageBlueprint.make({
+  params: {
+    defaultPath: '/my-page',
+  },
+});
+
+export default createFrontendPlugin({
   id: 'my-plugin',
+  extensions: [myPage],
 });
 ```
 
-<!--
+### `pluginId` option
 
-Note that this plugin is useless in itself, and you need to provide extra options to make it useful, in particular extensions.
+Each plugin needs an ID, which is used to uniquely identity the plugin within an entity Backstage system. The ID does not have to be globally unique across all of the NPM ecosystem, although you generally want to strive for that. It is not possible to install multiple plugins with the same ID in a single Backstage app.
 
- -->
+The plugin ID should generally be part of the of the package name and use kebab-case. See both the [frontend naming patterns section](./50-naming-patterns.md), as well as the [package metadata section](../../tooling/package-metadata.md#name) for more information.
 
-### Plugin ID
+### `extensions` option
 
-<!--
+These are the [extensions](./20-extensions.md) that the plugin provides to the app. Note that you should not export any of these extensions separately from the plugin package, as they can already by accessed via the `getExtension` method of the plugin instance using the extension ID.
 
-link to relevant docs
+The extensions that you provide to a plugin will have their `namespace` set to the plugin ID by default. For example, if you create an extensions using the `PageBlueprint` without any particular naming options and install that via a plugin with the ID `my-plugin`, the final extension ID will be `page:my-plugin`. You can read more about how this works in the [extension structure documentation](./20-extensions.md#extension-structure).
 
--->
+### `routes` and `externalRoutes` options
 
-### Plugin Extensions
+These are the routes that the plugin exposes to the app. The `routes` option declares all of the target routes that your plugin provides, i.e. routes that other plugins and link to. The `externalRoutes` option instead declares all the outgoing routes, i.e. routes that your plugins links to, which you can bind to the `routes` of other plugins. See the [routes documentation](./36-routes.md) for more information how to set up cross-plugin navigation.
 
-<!--
+### `featureFlags` option
 
- - Example of how this option is used in `createFrontendPlugin`
-
-link to relevant docs
-
--->
-
-### Plugin Routes
-
-<!--
-
- - Example of how this option is used in `createFrontendPlugin`
-
-link to relevant docs
-
--->
-
-### Plugin External Routes
-
-<!--
-
- - Example of how this option is used in `createFrontendPlugin`
-
-link to relevant docs
-
--->
-
-### Plugin Feature Flags
-
-<!--
-
- - Example of how this option is used in `createFrontendPlugin`
-
-link to relevant docs
-
--->
+This is a list of feature flag declarations that your plugin provides to the app. This makes sure that the feature flags are correctly registered and can be toggled in the app. To read a feature flag you can use the feature flags [Utility API](../architecture/33-utility-apis.md), accessible via `featureFlagsApiRef`.
 
 ## Installing a Plugin in an App
 
-<!--
-
-Quick intro, but link back to app docs for more details
-
- -->
+A plugin instance is considered an frontend feature and can be installed directly in any Backstage frontend app. See the [app documentation](./10-app.md) for more information about the different ways in which you can install new features in an app.