Remove NavItemBlueprint in favor of page-based nav discovery

Drop the deprecated NavItemBlueprint from the public API and migrate core
plugins to set title and icon on PageBlueprint instead. AppNav keeps
backward compatibility for legacy nav-item extensions via an internal
core.nav-item.target data ref.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

plugins/app/src/extensions/AppNav.test.tsx

@@ -18,38 +18,46 @@ import { screen, waitFor, within } from '@testing-library/react';
 import { renderTestApp } from '@backstage/frontend-test-utils';
 import {
   PageBlueprint,
-  NavItemBlueprint,
+  createExtension,
   createRouteRef,
 } from '@backstage/frontend-plugin-api';
+import { legacyNavItemTargetDataRef } from './legacyNavItem';
 
 const DEFAULT_CONFIG = {
   app: { baseUrl: 'http://localhost:3000' },
   backend: { baseUrl: 'http://localhost:7007' },
 };
 
+const mockRouteRef = createRouteRef();
+
 const mockPage = PageBlueprint.make({
   name: 'my-plugin',
   params: {
     title: 'My Plugin',
     icon: <span>icon</span>,
     path: '/my-plugin',
-    routeRef: createRouteRef(),
+    routeRef: mockRouteRef,
   },
 });
 
-const mockNavItem = NavItemBlueprint.make({
+const mockLegacyNavItem = createExtension({
+  kind: 'nav-item',
   name: 'my-plugin',
-  params: {
-    title: 'My Plugin',
-    icon: () => <span>icon</span>,
-    routeRef: createRouteRef(),
-  },
+  attachTo: { id: 'app/nav', input: 'items' },
+  output: [legacyNavItemTargetDataRef],
+  factory: () => [
+    legacyNavItemTargetDataRef({
+      title: 'Legacy Nav Title',
+      icon: () => <span>legacy icon</span>,
+      routeRef: mockRouteRef,
+    }),
+  ],
 });
 
 describe('AppNav', () => {
-  it('should show a nav item for a page with an enabled nav-item extension', async () => {
+  it('should show a nav item for a page with title and icon', async () => {
     renderTestApp({
-      extensions: [mockPage, mockNavItem],
+      extensions: [mockPage],
       config: DEFAULT_CONFIG,
     });
 
@@ -60,40 +68,24 @@ describe('AppNav', () => {
     });
   });
 
-  it('should hide a nav item when its nav-item extension is disabled via config', async () => {
-    renderTestApp({
-      extensions: [mockPage, mockNavItem],
-      config: {
-        ...DEFAULT_CONFIG,
-        app: {
-          ...DEFAULT_CONFIG.app,
-          extensions: [{ 'nav-item:test/my-plugin': false }],
-        },
+  it('should merge legacy nav item metadata when page has no explicit title', async () => {
+    const pageWithoutTitle = PageBlueprint.make({
+      name: 'legacy-plugin',
+      params: {
+        path: '/legacy-plugin',
+        routeRef: mockRouteRef,
+        icon: <span>page icon</span>,
       },
     });
 
+    renderTestApp({
+      extensions: [pageWithoutTitle, mockLegacyNavItem],
+      config: DEFAULT_CONFIG,
+    });
+
     await waitFor(() => {
       expect(
-        within(screen.getByRole('navigation')).queryByText('My Plugin'),
-      ).not.toBeInTheDocument();
-    });
-  });
-
-  it('should still show a nav item for a page without a nav-item extension', async () => {
-    renderTestApp({
-      extensions: [mockPage],
-      config: {
-        ...DEFAULT_CONFIG,
-        app: {
-          ...DEFAULT_CONFIG.app,
-          extensions: [{ 'nav-item:test/my-plugin': false }],
-        },
-      },
-    });
-
-    await waitFor(() => {
-      expect(
-        within(screen.getByRole('navigation')).getByText('My Plugin'),
+        within(screen.getByRole('navigation')).getByText('Legacy Nav Title'),
       ).toBeInTheDocument();
     });
   });

plugins/app/src/extensions/AppNav.tsx

@@ -18,7 +18,6 @@ import {
   createExtension,
   coreExtensionData,
   createExtensionInput,
-  NavItemBlueprint,
   routeResolutionApiRef,
   appTreeApiRef,
   IconComponent,
@@ -27,6 +26,7 @@ import {
   RouteResolutionApi,
   useApi,
 } from '@backstage/frontend-plugin-api';
+import { legacyNavItemTargetDataRef } from './legacyNavItem';
 import {
   NavContentBlueprint,
   NavContentComponent,
@@ -248,7 +248,7 @@ export const AppNav = createExtension({
   name: 'nav',
   attachTo: { id: 'app/layout', input: 'nav' },
   inputs: {
-    items: createExtensionInput([NavItemBlueprint.dataRefs.target]),
+    items: createExtensionInput([legacyNavItemTargetDataRef]),
     content: createExtensionInput([NavContentBlueprint.dataRefs.component], {
       singleton: true,
       optional: true,
@@ -264,7 +264,7 @@ export const AppNav = createExtension({
     yield coreExtensionData.reactElement(
       <NavContentRenderer
         legacyNavItems={inputs.items.map(item =>
-          item.get(NavItemBlueprint.dataRefs.target),
+          item.get(legacyNavItemTargetDataRef),
         )}
         Content={Content}
       />,

plugins/app/src/extensions/legacyNavItem.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  createExtensionDataRef,
+  IconComponent,
+  RouteRef,
+} from '@backstage/frontend-plugin-api';
+
+/**
+ * @internal
+ *
+ * Data ref for legacy nav-item extensions. Kept for backward compatibility with
+ * extensions created by older versions of the framework.
+ */
+export const legacyNavItemTargetDataRef = createExtensionDataRef<{
+  title: string;
+  icon: IconComponent;
+  routeRef: RouteRef<undefined>;
+}>().with({ id: 'core.nav-item.target' });