grafana · jackw · Apr 3, 2025 · Mar 20, 2025 · Mar 20, 2025 · Mar 20, 2025
@@ -1,7 +1,7 @@
 ---
 id: migrate-10_0_x-to-10_1_x
 title: 10.0.x to 10.1.x
-sidebar_position: 1
+sidebar_position: 4
 description: How to migrate plugins from Grafana version 10.0.x to 10.1.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-10_x-to-11_x
 title: 10.x to 11.x
-sidebar_position: 2
+sidebar_position: 3
 description: How to migrate plugins from Grafana version 10.x to 11.x
 keywords:
   - grafana

@@ -0,0 +1,151 @@
+---
+id: migrate-11_6_x-to-12_0_x
+title: 11.6.x to 12.0.x
+sidebar_position: 1
+description: How to migrate plugins from Grafana version 11.6.x to 12.0.x.
+keywords:
+  - grafana
+  - plugins
+  - plugin
+  - upgrading
+  - updating
+  - migration
+---
+
+# Migrate plugins from Grafana version 11.6.x to 12.0.x
+
+This guide helps you migrate plugins from Grafana version 11.6.x to 12.0.x.
+
+## Prerequisites
+
+Before starting the migration:
+
+- Back up your plugin code
+- Ensure your development environment is up to date
+- Familiarize yourself with [the reactive APIs](/how-to-guides/ui-extensions/) introduced in Grafana 11.4
+
+## Deprecated UI extension APIs removal
+
+The deprecated UI extension APIs have been removed in Grafana 12 in favor of the new reactive APIs introduced in Grafana 11.4. The following APIs have been removed:
+
+- `usePluginExtensions()`
+- `usePluginLinkExtensions()`
+- `usePluginComponentExtensions()`
+- `getPluginExtensions()`
+- `getPluginLinkExtensions()`
+- `getPluginComponentExtensions()`
+- `AppPlugin.configureExtensionLink()`
+- `AppPlugin.configureExtensionComponent()`
+
+Using any of these APIs in Grafana 12 will result in an error. Additionally, the TypeScript types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed.
+
+:::info
+If you need your plugin to work with both Grafana 12.0.x and older versions, you can implement runtime checks to conditionally use the appropriate APIs. For more information, refer to [Manage backwards compatibility with runtime checks](/how-to-guides/runtime-checks.md#example-conditionally-use-react-hooks).
+:::
+
+### AppPlugin.configureExtensionLink()
+
+Replace the `configureExtensionLink` method with the `addLink` method. Update the `extensionPointId` parameter to `targets`, which accepts either a `string` or `string[]`.
+
+```diff
+- new AppPlugin().configureExtensionLink({
++ new AppPlugin().addLink({
+- extensionPointId: PluginExtensionPoints.DashboardPanelMenu,
++ targets: PluginExtensionPoints.DashboardPanelMenu,
+    title: 'Component title 0',
+    description: 'Component description 0',
+    component: () => <div />,
+});
+```
+
+### AppPlugin.configureExtensionComponent()
+
+Replace the `configureExtensionComponent` method with the `addComponent` method. Update the `extensionPointId` parameter to `targets`, which accepts either a `string` or `string[]`.
+
+```diff
+- new AppPlugin().configureExtensionComponent({
++ new AppPlugin().addComponent({
+- extensionPointId: PluginExtensionPoints.CommandPalette,
++ targets: PluginExtensionPoints.CommandPalette,
+    title: 'Component title 0',
+    description: 'Component description 0',
+    component: () => <div />,
+});
+```
+
+### getPluginLinkExtensions() and usePluginLinkExtensions()
+
+Both the `getPluginLinkExtensions()` function and the `usePluginLinkExtensions()` React hook can be replaced with the `usePluginLinks()` React hook.
+
+```diff title="getPluginLinkExtensions"
+- const { extensions } = getPluginLinkExtensions({
++ const { links, isLoading } = usePluginLinks({
+    extensionPointId: 'grafana/dashboard/panel/menu/v1',
+    limitPerPlugin: 2,
+    context: {
+      panelId: '...',
+    },
+});
+```
+
+```diff title="usePluginLinkExtensions"
+- const { extensions, isLoading } = usePluginLinkExtensions({
++ const { links, isLoading } = usePluginLinks({
+    extensionPointId: 'grafana/dashboard/panel/menu/v1',
+    limitPerPlugin: 2,
+    context: {
+      panelId: '...',
+    },
+});
+```
+
+### getPluginComponentExtensions() and usePluginComponentExtensions()
+
+You can replace both the `getPluginComponentExtensions()` function and the `usePluginComponentExtensions()` React hook with the `usePluginComponents()` React hook.
+
+```diff title="getPluginComponentExtensions"
+- const { extensions } = getPluginComponentExtensions({
++ const { components, isLoading } = usePluginComponents({
+    extensionPointId: 'grafana/user/profile/tab/v1',
+    limitPerPlugin: 2,
+});
+```
+
+```diff title="usePluginComponentExtensions"
+- const { extensions, isLoading } = usePluginComponentExtensions({
++ const { components, isLoading } = usePluginComponents({
+    extensionPointId: 'grafana/user/profile/tab/v1',
+    limitPerPlugin: 2,
+});
+```
+
+### getPluginExtensions() and usePluginExtensions()
+
+Replace the `getPluginExtensions()` function and the `usePluginExtensions()` React hook based on their usage:
+
+- **For links:** Follow the [link extensions](https://github.com/grafana/plugin-tools/pull/1639/files#getpluginlinkextensions-and-usepluginlinkextensions) instructions.
+
+- **For components:** Follow the [component extensions](https://github.com/grafana/plugin-tools/pull/1639/files#getplugincomponentextensions-and-useplugincomponentextensions) instructions.
+
+- **For both links and components:** Use both `usePluginLinks` and `usePluginComponents`.
+
+### PluginExtensionLinkConfig and PluginExtensionComponentConfig
+
+The types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed from `@grafana/data`.Replace them with `PluginExtensionAddedLinkConfig` and `PluginExtensionAddedComponentConfig`, respectively.
+
+## Quick reference
+
+The following table summarizes the API changes with notes explaining the key differences:
+
+| Deprecated API                            | Equivalent API                                | Notes                                                                             |
+| ----------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AppPlugin.configureExtensionLink()`      | `AppPlugin.addLink()`                         | `extensionPointId` parameter renamed to `targets`, accepts `string` or `string[]` |
+| `AppPlugin.configureExtensionComponent()` | `AppPlugin.addComponent()`                    | `extensionPointId` parameter renamed to `targets`, accepts `string` or `string[]` |
+| `getPluginLinkExtensions()`               | `usePluginLinks()`                            | Returns `{ links, isLoading }` instead of `{ extensions }`                        |
+| `usePluginLinkExtensions()`               | `usePluginLinks()`                            | Returns `{ links, isLoading }` instead of `{ extensions }`                        |
+| `getPluginComponentExtensions()`          | `usePluginComponents()`                       | Returns `{ components, isLoading }` instead of `{ extensions }`                   |
+| `usePluginComponentExtensions()`          | `usePluginComponents()`                       | Returns `{ components, isLoading }` instead of `{ extensions, isLoading }`        |
+| `getPluginExtensions()`                   | `usePluginLinks()` or `usePluginComponents()` | Split into two separate hooks based on extension type (links or components)       |
+| `usePluginExtensions()`                   | `usePluginLinks()` or `usePluginComponents()` | Split into two separate hooks based on extension type (links or components)       |
+| `PluginExtensionComponentConfig`          | `PluginExtensionAddedComponentConfig`         | Updated type definition for component configuration                               |
+| `PluginExtensionLinkConfig`               | `PluginExtensionAddedLinkConfig`              | Updated type definition for link configuration                                    |
@@ -1,7 +1,7 @@
 ---
 id: migrate-6_x-to-7_0
 title: 6.x to 7.0
-sidebar_position: 8
+sidebar_position: 11
 description: How to upgrade plugins from Grafana version 6.x to 7.0.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-7_x-to-8_x
 title: 7.x to 8.x
-sidebar_position: 7
+sidebar_position: 10
 description: How to migrate Grafana v7.x plugins to the updated plugin system available in Grafana v8.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-8_3_x-to-8_4_x
 title: 8.3.x to 8.4.x
-sidebar_position: 6
+sidebar_position: 9
 description: How to migrate Grafana v8.3.x plugins to Grafana v8.4.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-8_x-to-9_x
 title: 8.x to 9.x
-sidebar_position: 5
+sidebar_position: 8
 description: How to migrate plugins from version 8.x to 9.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-9_1_x-to-9_2_x
 title: 9.1.x to 9.2.x
-sidebar_position: 4
+sidebar_position: 7
 description: How to migrate plugins from Grafana version 9.1.x to 9.2.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-9_3_x-to-9_4_x
 title: 9.3.x to 9.4.x
-sidebar_position: 3
+sidebar_position: 6
 description: How to migrate from Grafana 9.3.x to 9.4.x.
 keywords:
   - grafana

@@ -1,7 +1,7 @@
 ---
 id: migrate-9_x-to-10_x
 title: 9.x to 10.x
-sidebar_position: 2
+sidebar_position: 5
 description: How to migrate plugins from Grafana version 9.x to 10.x.
 keywords:
   - grafana