frontend-plugin-api: move app blueprints to new app-react package

Rugvip · Rugvip · commit 9ccf84e219cb · 2026-01-16T11:59:49.000+01:00
Signed-off-by: Patrik Oldsberg &lt;poldsberg@gmail.com&gt;
diff --git a/.changeset/bright-pumas-cut.md b/.changeset/bright-pumas-cut.md
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-app-backend': patch
+'@backstage/plugin-app-node': patch
+---
+
+Updated plugin metadata.
diff --git a/.changeset/common-heads-start.md b/.changeset/common-heads-start.md
@@ -0,0 +1,13 @@
+---
+'@backstage/plugin-app-react': patch
+---
+
+Moved the following blueprints from `@backstage/frontend-plugin-api`:
+
+- `IconBundleBlueprint`
+- `NavContentBlueprint`
+- `RouterBlueprint`
+- `SignInPageBlueprint`
+- `SwappableComponentBlueprint`
+- `ThemeBlueprint`
+- `TranslationBlueprint`
diff --git a/.changeset/curvy-zoos-drop.md b/.changeset/curvy-zoos-drop.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-app-react': minor
+---
+
+Initial release of this web library for `@backstage/plugin-app`.
diff --git a/.changeset/slick-beans-relax.md b/.changeset/slick-beans-relax.md
@@ -0,0 +1,13 @@
+---
+'@backstage/frontend-plugin-api': patch
+---
+
+The following blueprints are being restricted to only be used in app plugin overrides and modules. They are being moved to the `@backstage/plugin-app-react` package and have been deprecated:
+
+- `IconBundleBlueprint`
+- `NavContentBlueprint`
+- `RouterBlueprint`
+- `SignInPageBlueprint`
+- `SwappableComponentBlueprint`
+- `ThemeBlueprint`
+- `TranslationBlueprint`
diff --git a/.changeset/warm-pets-accept.md b/.changeset/warm-pets-accept.md
@@ -0,0 +1,13 @@
+---
+'@backstage/plugin-app': patch
+---
+
+The following blueprints are being restricted to only be used in app plugin overrides and modules. They will now produce a deprecation warning when used outside of the app plugin:
+
+- `IconBundleBlueprint`
+- `NavContentBlueprint`
+- `RouterBlueprint`
+- `SignInPageBlueprint`
+- `SwappableComponentBlueprint`
+- `ThemeBlueprint`
+- `TranslationBlueprint`
diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md
@@ -444,7 +444,7 @@ const app = createApp({
 Can be converted to the following extension:
 
 ```tsx
-import { SignInPageBlueprint } from '@backstage/frontend-plugin-api';
+import { SignInPageBlueprint } from '@backstage/plugin-app-react';
 
 const signInPage = SignInPageBlueprint.make({
   params: {
@@ -492,7 +492,7 @@ const app = createApp({
 Can be converted to the following extension:
 
 ```tsx
-import { ThemeBlueprint } from '@backstage/frontend-plugin-api';
+import { ThemeBlueprint } from '@backstage/plugin-app-react';
 
 const customLightThemeExtension = ThemeBlueprint.make({
   name: 'custom-light',
@@ -535,7 +535,7 @@ const app = createApp({
 Icons are now installed as extensions, using the `IconBundleBlueprint` to make new instances which can be added to the app.
 
 ```ts
-import { IconBundleBlueprint } from '@backstage/frontend-plugin-api';
+import { IconBundleBlueprint } from '@backstage/plugin-app-react';
 
 const exampleIconBundle = IconBundleBlueprint.make({
   name: 'example-bundle',
@@ -586,10 +586,8 @@ Can be converted to the following extension:
 
 ```tsx
 import { catalogTranslationRef } from '@backstage/plugin-catalog/alpha';
-import {
-  createTranslationMessages,
-  TranslationBlueprint,
-} from '@backstage/frontend-plugin-api';
+import { createTranslationMessages } from '@backstage/frontend-plugin-api';
+import { TranslationBlueprint } from '@backstage/plugin-app-react';
 
 const catalogTranslations = TranslationBlueprint.make({
   name: 'catalog-overrides',
@@ -705,7 +703,7 @@ export const navModule = createFrontendModule({
 Then in the actual implementation for the `SidebarContent` extension, you can provide something like the following, where you implement the entire `Sidebar` component.
 
 ```tsx title="in packages/app/src/modules/nav/Sidebar.tsx"
-import { NavContentBlueprint } from '@backstage/frontend-plugin-api';
+import { NavContentBlueprint } from '@backstage/plugin-app-react';
 
 export const SidebarContent = NavContentBlueprint.make({
   params: {
diff --git a/docs/frontend-system/building-plugins/03-common-extension-blueprints.md b/docs/frontend-system/building-plugins/03-common-extension-blueprints.md
@@ -23,6 +23,8 @@ Navigation item extensions are used to provide menu items that link to different
 
 Page extensions provide content for a particular route in the app. By default pages are attached to the app routes extensions, which renders the root routes.
 
+## Extension blueprints in `@backstage/plugin-app-react`
+
 ### SignInPage - [Reference](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.SignInPageBlueprint.html)
 
 Sign-in page extension have a single purpose - to implement a custom sign-in page. They are always attached to the app root extension and are rendered before the rest of the app until the user is signed in.
@@ -43,6 +45,14 @@ Icon bundle extensions provide the ability to replace or provide new icons to th
 
 Translation extension provide custom translation messages for the app. They can be used both to override the default english messages to custom ones, as well as provide translations for additional languages.
 
+### NavContent - [Reference](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.NavContentBlueprint.html)
+
+Nav content extensions allow you to replace the entire navbar with your own component. They are always attached to the app nav extension.
+
+### Router - [Reference](https://backstage.io/api/stable/variables/_backstage_frontend-plugin-api.RouterBlueprint.html)
+
+Router extensions allow you to replace the router component used by the app. They are always attached to the app root extension.
+
 ## Extension blueprints in `@backstage/plugin-catalog-react/alpha`
 
 These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Catalog plugin.
diff --git a/docs/frontend-system/building-plugins/06-swappable-components.md b/docs/frontend-system/building-plugins/06-swappable-components.md
@@ -52,11 +52,8 @@ In order to override a Swappable Component, you need to create a `SwappableCompo
 There are two different ways to add extensions to the `app` plugin, both are documented below in an example of overriding the `Progress` Swappable Component.
 
 ```tsx title="in packages/app/src/App.tsx"
-import {
-  Progress,
-  SwappableComponentBlueprint,
-  createFrontendModule,
-} from '@backstage/frontend-plugin-api';
+import { Progress, createFrontendModule } from '@backstage/frontend-plugin-api';
+import { SwappableComponentBlueprint } from '@backstage/plugin-app-react';
 import { MyCustomProgress } from './CustomProgress';
 import { createApp } from '@backstage/frontend-defaults';
 import appPlugin from '@backstage/plugin-app';
diff --git a/packages/frontend-plugin-api/report.api.md b/packages/frontend-plugin-api/report.api.md
@@ -1457,7 +1457,7 @@ export const googleAuthApiRef: ApiRef<
     SessionApi
 >;
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const IconBundleBlueprint: ExtensionBlueprint_2<{
   kind: 'icon-bundle';
   params: {
@@ -1522,7 +1522,7 @@ export const microsoftAuthApiRef: ApiRef<
     SessionApi
 >;
 
-// @public
+// @public @deprecated
 export const NavContentBlueprint: ExtensionBlueprint_2<{
   kind: 'nav-content';
   params: {
@@ -1923,7 +1923,7 @@ export type RouteFunc<TParams extends AnyRouteRefParams> = (
     : readonly [params: TParams]
 ) => string;
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const RouterBlueprint: ExtensionBlueprint_2<{
   kind: 'app-router-component';
   params: {
@@ -1998,7 +1998,7 @@ export namespace SessionState {
   export type SignedOut = typeof SessionState.SignedOut;
 }
 
-// @public
+// @public @deprecated
 export const SignInPageBlueprint: ExtensionBlueprint_2<{
   kind: 'sign-in-page';
   params: {
@@ -2066,7 +2066,7 @@ export interface SubRouteRef<
   readonly T: TParams;
 }
 
-// @public
+// @public @deprecated
 export const SwappableComponentBlueprint: ExtensionBlueprint_2<{
   kind: 'component';
   params: <Ref extends SwappableComponentRef<any>>(params: {
@@ -2150,7 +2150,7 @@ export interface SwappableComponentsApi {
 // @public
 export const swappableComponentsApiRef: ApiRef_2<SwappableComponentsApi>;
 
-// @public
+// @public @deprecated
 export const ThemeBlueprint: ExtensionBlueprint_2<{
   kind: 'theme';
   params: {
@@ -2186,7 +2186,7 @@ export type TranslationApi = {
 // @public (undocumented)
 export const translationApiRef: ApiRef<TranslationApi>;
 
-// @public
+// @public @deprecated
 export const TranslationBlueprint: ExtensionBlueprint_2<{
   kind: 'translation';
   params: {
diff --git a/packages/frontend-plugin-api/src/blueprints/IconBundleBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/IconBundleBlueprint.ts
@@ -21,7 +21,10 @@ const iconsDataRef = createExtensionDataRef<{
   [key in string]: IconComponent;
 }>().with({ id: 'core.icons' });
 
-/** @public */
+/**
+ * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#IconBundleBlueprint} instead.
+ */
 export const IconBundleBlueprint = createExtensionBlueprint({
   kind: 'icon-bundle',
   attachTo: { id: 'api:app/icons', input: 'icons' },
diff --git a/packages/frontend-plugin-api/src/blueprints/NavContentBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/NavContentBlueprint.ts
@@ -60,6 +60,7 @@ const componentDataRef = createExtensionDataRef<NavContentComponent>().with({
  * Creates an extension that replaces the entire nav bar with your own component.
  *
  * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#NavContentBlueprint} instead.
  */
 export const NavContentBlueprint = createExtensionBlueprint({
   kind: 'nav-content',
diff --git a/packages/frontend-plugin-api/src/blueprints/RouterBlueprint.tsx b/packages/frontend-plugin-api/src/blueprints/RouterBlueprint.tsx
@@ -21,7 +21,10 @@ const componentDataRef = createExtensionDataRef<
   (props: { children: ReactNode }) => JSX.Element | null
 >().with({ id: 'app.router.wrapper' });
 
-/** @public */
+/**
+ * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#RouterBlueprint} instead.
+ */
 export const RouterBlueprint = createExtensionBlueprint({
   kind: 'app-router-component',
   attachTo: { id: 'app/root', input: 'router' },
diff --git a/packages/frontend-plugin-api/src/blueprints/SignInPageBlueprint.tsx b/packages/frontend-plugin-api/src/blueprints/SignInPageBlueprint.tsx
@@ -44,6 +44,7 @@ const componentDataRef = createExtensionDataRef<
  * Creates an extension that replaces the sign in page.
  *
  * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#SignInPageBlueprint} instead.
  */
 export const SignInPageBlueprint = createExtensionBlueprint({
   kind: 'sign-in-page',
diff --git a/packages/frontend-plugin-api/src/blueprints/SwappableComponentBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/SwappableComponentBlueprint.ts
@@ -31,6 +31,7 @@ export const componentDataRef = createExtensionDataRef<{
  * Blueprint for creating swappable components from a SwappableComponentRef and a loader
  *
  * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#SwappableComponentBlueprint} instead.
  */
 export const SwappableComponentBlueprint = createExtensionBlueprint({
   kind: 'component',
diff --git a/packages/frontend-plugin-api/src/blueprints/ThemeBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/ThemeBlueprint.ts
@@ -25,6 +25,7 @@ const themeDataRef = createExtensionDataRef<AppTheme>().with({
  * Creates an extension that adds/replaces an app theme.
  *
  * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#ThemeBlueprint} instead.
  */
 export const ThemeBlueprint = createExtensionBlueprint({
   kind: 'theme',
diff --git a/packages/frontend-plugin-api/src/blueprints/TranslationBlueprint.ts b/packages/frontend-plugin-api/src/blueprints/TranslationBlueprint.ts
@@ -25,6 +25,7 @@ const translationDataRef = createExtensionDataRef<
  * Creates an extension that adds translations to your app.
  *
  * @public
+ * @deprecated Use {@link @backstage/plugin-app-react#TranslationBlueprint} instead.
  */
 export const TranslationBlueprint = createExtensionBlueprint({
   kind: 'translation',
diff --git a/plugins/app-backend/package.json b/plugins/app-backend/package.json
@@ -8,7 +8,8 @@
     "pluginPackages": [
       "@backstage/plugin-app",
       "@backstage/plugin-app-backend",
-      "@backstage/plugin-app-node"
+      "@backstage/plugin-app-node",
+      "@backstage/plugin-app-react"
     ]
   },
   "publishConfig": {
diff --git a/plugins/app-node/package.json b/plugins/app-node/package.json
@@ -8,7 +8,8 @@
     "pluginPackages": [
       "@backstage/plugin-app",
       "@backstage/plugin-app-backend",
-      "@backstage/plugin-app-node"
+      "@backstage/plugin-app-node",
+      "@backstage/plugin-app-react"
     ]
   },
   "publishConfig": {
diff --git a/plugins/app-react/.eslintrc.js b/plugins/app-react/.eslintrc.js
@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
diff --git a/plugins/app-react/README.md b/plugins/app-react/README.md
@@ -0,0 +1,5 @@
+# @backstage/plugin-app-react
+
+Welcome to the web library package for the app plugin!
+
+_This plugin was created through the Backstage CLI_
diff --git a/plugins/app-react/catalog-info.yaml b/plugins/app-react/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-plugin-app-react
+  title: '@backstage/plugin-app-react'
+  description: Web library for the app plugin
+spec:
+  lifecycle: experimental
+  type: backstage-web-library
+  owner: framework-maintainers
diff --git a/plugins/app-react/package.json b/plugins/app-react/package.json
@@ -0,0 +1,68 @@
+{
+  "name": "@backstage/plugin-app-react",
+  "version": "0.0.0",
+  "description": "Web library for the app plugin",
+  "backstage": {
+    "role": "web-library",
+    "pluginId": "app",
+    "pluginPackages": [
+      "@backstage/plugin-app",
+      "@backstage/plugin-app-backend",
+      "@backstage/plugin-app-node",
+      "@backstage/plugin-app-react"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/app-react"
+  },
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "start": "backstage-cli package start",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/core-plugin-api": "workspace:^",
+    "@backstage/frontend-plugin-api": "workspace:^",
+    "@material-ui/core": "^4.9.13"
+  },
+  "devDependencies": {
+    "@backstage/cli": "workspace:^",
+    "@backstage/frontend-test-utils": "workspace:^",
+    "@backstage/test-utils": "workspace:^",
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.2",
+    "react-dom": "^18.0.2",
+    "react-router-dom": "^6.3.0"
+  },
+  "peerDependencies": {
+    "@types/react": "^17.0.0 || ^18.0.0",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0",
+    "react-router-dom": "^6.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  }
+}
diff --git a/plugins/app-react/report.api.md b/plugins/app-react/report.api.md
diff --git a/plugins/app-react/src/blueprints/index.ts b/plugins/app-react/src/blueprints/index.ts
diff --git a/plugins/app-react/src/index.ts b/plugins/app-react/src/index.ts
diff --git a/plugins/app-react/src/setupTests.ts b/plugins/app-react/src/setupTests.ts
diff --git a/plugins/app/package.json b/plugins/app/package.json
diff --git a/plugins/app/src/extensions/AppNav.tsx b/plugins/app/src/extensions/AppNav.tsx
diff --git a/plugins/app/src/extensions/AppRoot.tsx b/plugins/app/src/extensions/AppRoot.tsx
diff --git a/plugins/app/src/extensions/AppThemeApi.tsx b/plugins/app/src/extensions/AppThemeApi.tsx
diff --git a/plugins/app/src/extensions/IconsApi.ts b/plugins/app/src/extensions/IconsApi.ts
diff --git a/plugins/app/src/extensions/TranslationsApi.tsx b/plugins/app/src/extensions/TranslationsApi.tsx
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@backstage/plugin-app-react': minor
 +---
++
 +Initial release of this web library for `@backstage/plugin-app`.