Merge pull request #30929 from backstage/blam/nfs/docs/tting

`docs(nfs)`: update some more docs
2025-08-19 14:55:58 +02:00
parent d4e20014a3 536b76f405
commit 2974f7f52b
21 changed files with 40 additions and 41 deletions
@@ -5,8 +5,6 @@ sidebar_label: Overview
 description: The structure and architecture of the new Frontend System
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## Building Blocks

 This section introduces the high-level building blocks upon which this new
@@ -5,8 +5,6 @@ sidebar_label: App
 description: App instances
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## The App Instance

 The app instance is the main entry point for creating a frontend app. It doesn't do much on its own, but is instead responsible for wiring things together that have been provided as features from other parts of the system.
@@ -5,8 +5,6 @@ sidebar_label: Plugins
 description: Frontend plugins
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of 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, and APIs; as well as extensions and features for other plugins, such as entity page cards and content for the Software Catalog, or result list items for the search plugin.
@@ -5,8 +5,6 @@ sidebar_label: Extensions
 description: Frontend extensions
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 As mentioned in the [previous section](./10-app.md), Backstage apps are built up from a tree of extensions. This section will go into more detail about what extensions are, how to create and use them, and how to create your own extensibility patterns.

 ## Extension Structure
@@ -5,8 +5,6 @@ sidebar_label: Extensions Blueprints
 description: Frontend extensions
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 The `createExtension` function and related APIs is considered a low-level building and fairly advanced building block, and is not typically what you would use when building plugins and features. Instead, the core APIs and plugins provide extension blueprints that makes it easier to create extensions for specific usages. These blueprints accept a number of parameters that is up to each blueprint to define, and then creates a new extension using the provided parameters. New blueprints are created using the `createExtensionBlueprint` function, and are by convention exported with the symbol `<Kind>Blueprint`. If you are curious about what blueprints are available from a plugin or package, look for `*Blueprint` exports in the package's API, for plugins these are typically found in the `*-react` package.

 ## Creating an extension from a blueprint
@@ -5,8 +5,6 @@ sidebar_label: Extension Overrides
 description: Frontend extension overrides
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## Introduction

 An important customization point in the frontend system is the ability to override existing extensions. It can be used for anything from slight tweaks to the extension logic, to completely replacing an extension with a custom implementation. While extensions are encouraged to make themselves configurable, there are many situations where you need to override an extension to achieve the desired behavior. The ability to override extensions should be kept in mind when building plugins, and can be a powerful tool to allow for deeper customizations without the need to re-implement large parts of the plugin.
@@ -5,8 +5,6 @@ sidebar_label: Value References
 description: Value References
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 <!--

 Describe the generic concept of references as used for ApiRef, ExtensionDataRef, RouteRef, ComponentRef, etc.
@@ -5,8 +5,6 @@ sidebar_label: Routes
 description: Frontend routes
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## Introduction

 Each Backstage plugin is an isolated piece of functionality that doesn't typically communicate directly with other plugins. In order to achieve this, there are many parts of the frontend system that provide a layer of indirection for cross-plugin communication, and the routing system is one of them.
@@ -422,7 +420,7 @@ export default createFrontendPlugin({

 ## Route Aliases - Overriding Routed Extensions in Modules

-It is possible to [override extensions of a plugin using a module](./25-extension-overrides.md#creating-a-frontend-module). In some cases the extension you're overriding may require a route reference. You could import import the plugin instance and access the it via the `routes` property, but this creates a direct dependency on the plugin and risks leading to package duplication issues that would also break the route reference.
+It is possible to [override extensions of a plugin using a module](./25-extension-overrides.md#creating-a-frontend-module). In some cases the extension you're overriding may require a route reference. You could import the plugin instance and access the it via the `routes` property, but this creates a direct dependency on the plugin and risks leading to package duplication issues that would also break the route reference.

 Instead of accessing the route reference directly, you can create a new route reference that acts as an alias for the original one from the plugin. For example, you can override the catalog index page with a custom one like this:

@@ -5,8 +5,6 @@ sidebar_label: Naming Patterns
 description: Naming patterns in the frontend system
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 These are the naming patterns to adhere to within the frontend system. They help us keep exports and IDs consistent across packages and make it easier to understand the usage and intent of exports and IDs.

 As a rule, all names should be camel case, with the exceptions of plugin and extension IDs, which should use kebab case.
@@ -5,8 +5,6 @@ sidebar_label: Changelog
 description: Changelog documentation for different versions of the frontend system core APIs.
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## Introduction

 This section provides migration guides for different versions of the frontend system core APIs. Each guide will provide a summary of the changes that have been made for a particular Backstage release, and how to update your usage of the core APIs.
@@ -5,8 +5,6 @@ sidebar_label: Overview
 description: Building frontend apps using the new frontend system
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 To get set up quickly with your own Backstage project you can create a Backstage App.

 A Backstage App is a monorepo setup that includes everything you need to run Backstage in your own environment.
@@ -956,6 +956,45 @@ Once the cleanup is complete you should be left with clean entity pages that are

 Migrating across the tabs for the Entity Pages should be as simple as removing the `EntityLayout.Route` for each of the plugins that provide tab content, and then this tab should be sourced from the `EntityContent` extensions created by the plugins themselves which will be automatically detected and added to the App.

+## Enable the new templates for `yarn new`
+
+It's encouraged that once you switch over to using the new frontend system, that new plugins that you create are using the new frontend system. This means that you're not instantly creating legacy plugins that will eventually need migration.
+
+This practice is also pretty important early on, as it's going to help you get familiar with the practices of the new frontend system.
+
+When creating a new Backstage app with `create-app` and using the `--next` flag you'll automatically get these choices in the `yarn new` command, but if you want to bring these templates to an older app, you can add the following to your root `package.json`:
+
+```json
+{
+  ...
+  "scripts": {
+    ...
+    "new": "backstage-cli new"
+  },
+  "backstage": {
+    "cli": {
+      "new": {
+        "globals": {
+          "license": "UNLICENSED"
+        },
+        "templates": [
+          "@backstage/cli/templates/new-frontend-plugin",
+          "@backstage/cli/templates/new-frontend-plugin-module",
+          "@backstage/cli/templates/backend-plugin",
+          "@backstage/cli/templates/backend-plugin-module",
+          "@backstage/cli/templates/plugin-web-library",
+          "@backstage/cli/templates/plugin-node-library",
+          "@backstage/cli/templates/plugin-common-library",
+          "@backstage/cli/templates/web-library",
+          "@backstage/cli/templates/node-library",
+          "@backstage/cli/templates/scaffolder-backend-module"
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Troubleshooting

 We'd recommend that you install the `app-visualizer` plugin to help your troubleshooting. If you run `yarn add @backstage/plugin-app-visualizer` in `packages/app` it should be automatically added to the sidebar, and available on `/visualizer`.
@@ -5,8 +5,6 @@ sidebar_label: Overview
 description: Building frontend plugins using the new frontend system
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 This section covers how to build your own frontend [plugins](../architecture/15-plugins.md) and
 [overrides](../architecture/25-extension-overrides.md). They are sometimes collectively referred to as
 frontend _features_, and what you install to build up a Backstage frontend [app](../architecture/10-app.md).
@@ -5,8 +5,6 @@ sidebar_label: Testing
 description: Testing plugins in the frontend system
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 # Testing Frontend Plugins

 :::note Note
@@ -5,8 +5,6 @@ sidebar_label: Common Extension Blueprints
 description: Extension blueprints provided by the frontend system and core features
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 This section covers many of the [extension blueprints](../architecture/23-extension-blueprints.md) available at your disposal when building Backstage frontend plugins.

 ## Extension blueprints in `@backstage/frontend-plugin-api`
@@ -5,8 +5,6 @@ sidebar_label: Built-in data refs
 description: Configuring or overriding built-in extension data references
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 To have a better understanding of extension data references please read [the corresponding architecture section](../architecture/20-extensions.md#extension-data) first.

 ## Built-in extension data references
@@ -5,8 +5,6 @@ sidebar_label: Introduction
 description: The Frontend System
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 ## Status

 The new frontend system is in alpha, and only a few plugins support the system so far. We do not yet recommend migrating any apps to the new system. If you add support for the new system to your plugin, please do so under a `/alpha` sub-path export.
@@ -5,8 +5,6 @@ sidebar_label: Overview
 description: Working with Utility APIs in the New Frontend System
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 As described [in the architecture section](../architecture/33-utility-apis.md), utility APIs are pieces of shared functionality - interfaces that can be requested by plugins to use. They are defined by a TypeScript interface as well as a reference (an "API ref") used to access its implementation. They can be provided both by plugins and the core framework, and are themselves [extensions](../architecture/20-extensions.md) that can accept inputs, be declaratively configured in your app-config, or transparently be replaced entirely with custom implementations that fulfill the same contract.

 ## Creating utility APIs
@@ -5,8 +5,6 @@ sidebar_label: Creating APIs
 description: Creating new utility APIs in your plugins and app
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 This section describes how to make a Utility API from scratch, or to add configurability and inputs to an existing one. If you are instead interested in migrating an existing Utility API from the old frontend system, check out the [Migrating APIs section](../building-plugins/05-migrating.md#migrating-apis).

 ## Creating the Utility API contract
@@ -5,8 +5,6 @@ sidebar_label: Consuming APIs
 description: Consuming utility APIs
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 All of the utility API extensions that were passed into your app through installed plugins, get instantiated and configured in the right order by the framework, and are then made available for consumption. You can interact with these instances in the following ways.

 ## Via React hooks
@@ -5,8 +5,6 @@ sidebar_label: Configuring
 description: Configuring, extending, and overriding utility APIs
 ---

-> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
-
 Utility APIs are extensions and can therefore optionally be amended with configurability, as well as inputs that other extensions attach themselves to. This section describes how to make use of that as a consumer of such utility APIs.

 ## Configuring