Skip to main content

Migrate plugins from Grafana version 13.1.x to 13.2.x

Follow these instructions to migrate plugins from Grafana version 13.1.x to 13.2.x.

Grafana now runs React 19​

As of Grafana 13.2.0, Grafana core has completed its upgrade from React 18 to React 19. Grafana shares a single React instance with all loaded plugins at runtime, which means plugins running in Grafana 13.2.0 or later run on React 19.

To match the runtime, the @grafana/* npm packages released with Grafana core—such as @grafana/data, @grafana/runtime, @grafana/ui, @grafana/schema, and @grafana/i18n—declare a react and react-dom peer dependency of >=19 from version 13.2.0. When you update your plugin's @grafana/* dependencies to 13.2.0, you must also update React and its type packages in your plugin. Otherwise, your package manager reports a peer dependency conflict (npm fails with an ERESOLVE error).

Prerequisites​

Before updating your dependencies, make sure your plugin code is React 19 compatible. The 12.x to 13.x migration guide covers this in detail:

  • Run @grafana/react-detect to find incompatible code and dependencies.
  • Apply the jsx-runtime fix if your plugin bundles react/jsx-runtime.
  • Replace usage of APIs removed in React 19, such as ReactDOM.render, findDOMNode, defaultProps on function components, and string refs.

If you have already completed these steps, your plugin runs correctly on both React 18 and React 19 runtimes, and you only need to update your dependencies and types.

Update your npm dependencies​

Update the following packages in your plugin's package.json:

 "dependencies": {
-  "@grafana/data": "13.1.0",
-  "@grafana/i18n": "13.1.0",
-  "@grafana/runtime": "13.1.0",
-  "@grafana/schema": "13.1.0",
-  "@grafana/ui": "13.1.0",
-  "react": "^18.3.0",
-  "react-dom": "^18.3.0"
+  "@grafana/data": "13.2.0",
+  "@grafana/i18n": "13.2.0",
+  "@grafana/runtime": "13.2.0",
+  "@grafana/schema": "13.2.0",
+  "@grafana/ui": "13.2.0",
+  "react": "^19.2.0",
+  "react-dom": "^19.2.0"
 },
 "devDependencies": {
-  "@types/react": "^18.3.0",
-  "@types/react-dom": "^18.3.0",
+  "@types/react": "^19.2.0",
+  "@types/react-dom": "^19.2.0",
 }

Then reinstall your dependencies:

npm install
info

The React version in your package.json doesn't change the React version your plugin runs on inside Grafana—the Grafana runtime provides React. Updating these packages aligns your local development, type checking, and unit test environments with the Grafana 13.2.0 runtime.

Update testing and development dependencies​

  • @testing-library/react supports React 19 from version 16.1.0. Use ^16.3.0 or later to match the version scaffolded by create-plugin.
  • If you use @grafana/scenes, check the scenes release notes for a release that declares React 19 peer dependency support before updating.

Fix TypeScript errors​

Updating to @types/react 19 might surface type errors in your plugin. These are the most common changes:

The global JSX namespace was removed​

Replace usage of the global JSX namespace with React.JSX:

-const element: JSX.Element = <MyPanel />;
+const element: React.JSX.Element = <MyPanel />;

useRef requires an argument​

useRef now requires an initial value:

-const ref = useRef<HTMLDivElement>();
+const ref = useRef<HTMLDivElement>(null);

ReactElement props default to unknown​

If you access element.props on a ReactElement typed without an explicit props type, the props are now typed as unknown instead of any. Add an explicit type argument where needed.

To automate most of these changes, run the React 19 types codemod preset from the root of your plugin:

npx types-react-codemod@latest preset-19 ./src

Refer to the React 19 upgrade guide for the full list of TypeScript changes.

Support for older Grafana versions​

Which React features you can safely use depends on the range of Grafana versions your plugin supports in the grafanaDependency property of plugin.json:

  • If your plugin supports Grafana versions older than 13.2.0, your code runs on React 18 in those versions. Keep your code compatible with both React 18 and React 19, and don't use React 19-only APIs such as use, ref cleanup functions, or passing ref as a regular prop to function components.
  • If you set grafanaDependency to >=13.2.0, your plugin always runs on React 19 and you can adopt React 19 features.
note

The 12.x to 13.x migration guide previously advised against adopting React 19 functionality while the migration was in progress. With Grafana 13.2.0 released, that restriction no longer applies to plugins that require Grafana 13.2.0 or later.

Test your plugin​

  1. Run your type checks and unit tests. Your unit tests now run against React 19 locally, which might surface issues that the Grafana runtime would also hit:

    npm run typecheck
    npm run test:ci

  2. Run your plugin against Grafana 13.2.0 and navigate through its features to verify expected behavior:

    GRAFANA_VERSION=13.2.0 docker compose up --build

  3. If your plugin still supports older Grafana versions, also verify it against the oldest version in your grafanaDependency range to confirm backward compatibility with React 18 runtimes.

Update CI pipelines​

If you use the e2e testing workflow with the plugin-actions/e2e-version action, the action automatically resolves the released Grafana 13.2.0 image from your plugin's grafanaDependency.

If you enabled the React 19 developer preview image during the preview period, remove the skip-grafana-react-19-preview-image input—the preview image is superseded by the 13.2.0 release, and the input has been removed from the latest versions of the action:

  - name: Resolve Grafana E2E versions
    id: resolve-versions
    uses: grafana/plugin-actions/e2e-version@e2e-version/v1.2.1
-   with:
-     skip-grafana-react-19-preview-image: false