From e5a1b33b0bdbac6f17bd5d59840827d93a53f49a Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 23 Nov 2025 13:04:53 +0100
Subject: [PATCH] docs/frontend-system: remove use of compatWrapper

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../building-apps/08-migrating.md             | 52 ++++++++-----------
 .../building-plugins/05-migrating.md          |  8 +--
 2 files changed, 24 insertions(+), 36 deletions(-)

diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md
index 2b248b12a7..1fd74becfc 100644
--- a/docs/frontend-system/building-apps/08-migrating.md
+++ b/docs/frontend-system/building-apps/08-migrating.md
@@ -676,8 +676,6 @@ createApp({
         AppRootWrapperBlueprint.make({
           name: 'custom-app-barrier',
           params: {
-            // Whenever your component uses legacy core packages, wrap it with "compatWrapper"
-            // e.g. props => compatWrapper(<CustomAppBarrier {...props} />)
             Component: CustomAppBarrier,
           },
         }),
@@ -700,41 +698,37 @@ import { SidebarContent } from './Sidebar';
 
 export const navModule = createFrontendModule({
   pluginId: 'app',
-  extensions: [SidebarContent],
+  extensions: [sidebarContent],
 });
 ```
 
-Then in the actual implementation for the `SidebarContent` extension, you can provide something like the following, where the component that is passed to the `compatWrapper` is the entire `Sidebar` component from your `Root` component.
-
-The `compatWrapper` is there to ensure that any legacy plugins using things like `useRouteRef` work well in the new system, so if you run into some errors which look like compatibility issues, make sure that this wrapper is used in the relevant places.
+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 { compatWrapper } from '@backstage/core-compat-api';
 import { NavContentBlueprint } from '@backstage/frontend-plugin-api';
 
-export const SidebarContent = NavContentBlueprint.make({
+export const sidebarContent = NavContentBlueprint.make({
   params: {
-    component: ({ items }) =>
-      compatWrapper(
-        <Sidebar>
-          <SidebarLogo />
-          <SidebarGroup label="Search" icon={<SearchIcon />} to="/search">
-            <SidebarSearchModal />
-          </SidebarGroup>
-          <SidebarDivider />
-          <SidebarGroup label="Menu" icon={<MenuIcon />}>
-            ...
-          </SidebarGroup>
-          <SidebarGroup label="Plugins">
-            <SidebarScrollWrapper>
-              {/* Items in this group will be scrollable if they run out of space */}
-              {items.map((item, index) => (
-                <SidebarItem {...item} key={index} />
-              ))}
-            </SidebarScrollWrapper>
-          </SidebarGroup>
-        </Sidebar>,
-      ),
+    component: ({ items }) => (
+      <Sidebar>
+        <SidebarLogo />
+        <SidebarGroup label="Search" icon={<SearchIcon />} to="/search">
+          <SidebarSearchModal />
+        </SidebarGroup>
+        <SidebarDivider />
+        <SidebarGroup label="Menu" icon={<MenuIcon />}>
+          ...
+        </SidebarGroup>
+        <SidebarGroup label="Plugins">
+          <SidebarScrollWrapper>
+            {/* Items in this group will be scrollable if they run out of space */}
+            {items.map((item, index) => (
+              <SidebarItem {...item} key={index} />
+            ))}
+          </SidebarScrollWrapper>
+        </SidebarGroup>
+      </Sidebar>
+    ),
   },
 });
 ```
diff --git a/docs/frontend-system/building-plugins/05-migrating.md b/docs/frontend-system/building-plugins/05-migrating.md
index 4940e0526b..b0e9816a17 100644
--- a/docs/frontend-system/building-plugins/05-migrating.md
+++ b/docs/frontend-system/building-plugins/05-migrating.md
@@ -106,7 +106,6 @@ it can be migrated as the following, keeping in mind that you may need to switch
 
 ```tsx
 import { PageBlueprint } from '@backstage/frontend-plugin-api';
-import { compatWrapper } from '@backstage/core-compat-api';
 
 const fooPage = PageBlueprint.make({
   params: {
@@ -116,12 +115,7 @@ const fooPage = PageBlueprint.make({
     // You can reuse the existing routeRef.
     routeRef: rootRouteRef,
     // these inputs usually match the props required by the component.
-    loader: () =>
-      import('./components/').then(m =>
-        // The compatWrapper utility allows you to keep using @backstage/core-plugin-api in the
-        // implementation of the component and switch to @backstage/frontend-plugin-api later.
-        compatWrapper(<m.FooPage />),
-      ),
+    loader: () => import('./components/').then(m => <m.FooPage />),
   },
 });
 ```