diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md index f8a7bbde1d..33567493bd 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md index 35eaed0cf1..de50eefebe 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md new file mode 100644 index 0000000000..1cbe47cfb1 --- /dev/null +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -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: () =>
, +}); +``` + +### 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: () =>
, +}); +``` + +### 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 | diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md index 80d9423b2f..99b2362aee 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md index 92f4905f15..056b6e0164 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md index aa74abf835..4c26e1dfc2 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md index dffcff5444..c582a4c363 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md index bb9f8ed3d3..5b51944f2b 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md index 558f5d8c0f..c0c59e7a1d 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md @@ -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 diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md index 6c7d806642..8ce2d46bd0 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md @@ -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 diff --git a/docusaurus/website/babel.config.js b/docusaurus/website/babel.config.js deleted file mode 100644 index e00595dae7..0000000000 --- a/docusaurus/website/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -};