WIP

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/frontend-system/building-apps/01-index.md

@@ -74,7 +74,7 @@ Remember that package extensions that are not auto-discovered must be manually a
 
 ### Configure extensions individually
 
-It is possible to enable, disable and configure extensions individually in the `app-config.yaml` config file. To get familiar with what is available for app extensions personalization, go to the [built-in extensions](./02-built-in-extensions.md) documentation. For plugin customizations, we recommend that you read the instructions in each plugin's README file.
+It is possible to enable, disable and configure extensions individually in the `app-config.yaml` config file. To get familiar with what is available for app extensions personalization, go to the [built-in extensions](./03-built-in-extensions.md) documentation. For plugin customizations, we recommend that you read the instructions in each plugin's README file.
 
 ### Customize or override built-in extensions
 
@@ -139,7 +139,7 @@ const app = createApp({
     // Calls an async utility method that fetches the config object from the server
     const config = await getConfigFromServer();
     // Feel free to manipulate the config object before returning it
-    // A common example is conditionally modify the config based on the running enviroment
+    // A common example is conditionally modify the config based on the running environment
     return { config };
   },
 });

docs/frontend-system/building-apps/02-configuring-extensions.md

@@ -0,0 +1,97 @@
+---
+id: configuring-extensions
+title: Configuring Extensions in the App
+sidebar_label: Configuring Extensions
+# prettier-ignore
+description: Documentation for how to configure extensions in a Backstage app
+---
+
+All extensions in a Backstage app can be configured through static configuration. This configuration is all done under a the `app.extensions` configuration key. For more general information on how to write configuration for Backstage, see the section on [writing configuration](../../conf/writing.md).
+
+## Extension Configuration Schema
+
+This section focuses on the format of the `app.extensions` configuration and the various shorthands that are available.
+
+The most complete and verbose format for configuring an individual extensions is as follows:
+
+```yaml
+app:
+  extensions:
+    - <id>:
+        attachTo:
+          id: <parent-id>
+          input: <input-name>
+        disabled: <true/false>
+        config: <extension-specific-config->
+```
+
+All of the top-level fields are optional: `attachTo`, `disabled`, and `config`. Every extension implementation must provide defaults for all of these fields that will be used if they are not provided in the configuration.
+
+Note that `app.extensions` is always an array rather than an object. For example, the following is invalid:
+
+```yaml title="INVALID"
+app:
+  extensions:
+    <id>: # Invalid, this should be an array item, `app.extensions` is now an object
+      config: ...
+```
+
+In addition to this schema, there are a number of shorthands available:
+
+Rather than a full object, you can specify just the ID of the extension as a string. This is equivalent to setting `disabled` to `false`:
+
+```yaml
+app:
+  extensions:
+    - ‘<id>’
+```
+
+You can enable/disable individual extension by ID, in this case the value is a boolean:
+
+```yaml
+extensions:
+  - <id>: <true/false>
+```
+
+You can override the implementation of an extension by ID, in this case the value is a string:
+
+```yaml
+extensions:
+  - <id>: ‘<implementation-reference>’
+```
+
+You can **create a new extension instance with a generated ID** by including an input name in the key:
+
+```yaml
+extensions:
+  - <parent-id>/<parent-input>:
+      extension: <implementation-reference>
+      config: <configuration-object>
+```
+
+This syntax is only for use in the app configuration itself, every extension provided by default from a plugin must have an explicit ID. For example, the following two configurations are equivalent, except that the former does not have an explicit instance ID:
+
+```yaml
+extensions:
+  # Generated ID
+  - core.router/routes:
+      extension: '@backstage/plugin-tech-radar#TechRadarPage'
+  # Explicit ID
+  - tech-radar.page:
+      at: core.router/routes
+      extension: '@backstage/plugin-tech-radar#TechRadarPage'
+```
+
+Lastly, if you do not need to provide additional configuration, you can combine the key input format with the implementation value format as a shorthand for creating a new extension instance with a generated ID and no configuration:
+
+```yaml
+extensions:
+  - <parent-id>/<parent-input>: ‘<implementation-reference>’
+```
+
+For example:
+
+```yaml
+extensions:
+  - core.router/routes: '@backstage/plugin-tech-radar#TechRadarPage'
+```

docs/frontend-system/building-apps/08-migrating.md

@@ -157,7 +157,7 @@ Declaring features flags in the app is no longer supported, move these declarati
 
 ### `components`
 
-Many app components are now installed as extensions instead using `createComponentExtension`. See the section on [configuring app components](./index.md#TODO) for more information.
+Many app components are now installed as extensions instead using `createComponentExtension`. See the section on [configuring app components](./01-index.md#configure-your-app) for more information.
 
 The `Router` component is now a built-in extension that you can override using `createRouterExtension`.
 
@@ -433,7 +433,3 @@ export default app.createRoot(
 ```
 
 Any app root wrapper needs to be migrated to be an extension instead, using `createAppRootWrapperExtension`. Note that if you have multiple wrappers they must be completely independent of each other, the order in which the appear in the React tree should not matter. If that is not the case then you should group them into a single wrapper.
-
-## Tools
-
-- App Visualizer

microsite/sidebars.json

@@ -447,6 +447,7 @@
         "label": "Building Apps",
         "items": [
           "frontend-system/building-apps/index",
+          "frontend-system/building-apps/configuring-extensions",
           "frontend-system/building-apps/built-in-extensions",
           "frontend-system/building-apps/migrating"
         ]