React 19 Upgrade: Ensure your plugin is compatible with React 19

[tolzhabayev]

Context

As part of the Grafana 13 release in April, we are updating Grafana's frontend from React 18 to React 19. Since Grafana shares a single React instance with all loaded plugins at runtime, plugins that rely on removed or renamed React APIs may break when Grafana 13 ships.

For full background, see the public blog post: React 19 is coming to Grafana: what plugin developers need to know.

What you need to do

1. Run the compatibility scanner

From the root of your plugin (where package.json lives), run:

npm run build
npx -y @grafana/react-detect@latest

This will scan your built output and source code for known React 19 breaking changes, including:

• Removal of propTypes checks and defaultProps on function components
• Removal of legacy context API (contextTypes and getChildContext)
• Removal of string refs
• Removal of createFactory
• Removal of ReactDOM.findDomNode
• Removal of ReactDOM.render and ReactDOM.unmountComponentAtNode
• Renaming of __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED

Note: The tool can produce false positives, especially when code supports multiple React versions. Treat it as a starting point.

2. Fix any issues found

• Source code issues — follow the suggestions from the CLI output and the React 19 upgrade guide.
• Dependency issues — update flagged dependencies to their latest versions and verify they support React 19. If a dependency does not support React 19, look for a fork or replacement.

3. Verify locally with the React 19 dev preview

We publish a Docker image with React 19 enabled for manual testing. Run from your plugin's root:

GRAFANA_VERSION=dev-preview-react19 docker compose up --build

Navigate through your plugin's features and confirm everything works. If you have e2e tests, run them against this image as well.

4. Verify in CI

If you're using the plugin-actions/e2e-version workflow, add the following input to also test against the React 19 preview image:

- 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

If you are using plugin-ci-workflows make sure you are using version that is >=6.0.0 and you should see the react test running as part of your e2e testing job matrix by default.

5. Publish an updated version

Once verified, publish a new version of your plugin so it is ready for users when Grafana 13 ships. Do this before March 20th 2025.

Dashboard

You can check the current React 19 compatibility status of your plugin (and others) on this internal dashboard:

React 19 Breaking Changes — Plugin Analysis

Need help?

Reach out in #proj-react-19 on Slack — we're happy to help with any questions or issues you run into.

More details

• Blog post with more details
• Migration guide