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 details, see our 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.
• __SECRET_INTERNALS issues — these are the most likely cause of plugin loading failures. To resolve them, extend your plugin's webpack config to externalize react/jsx-runtime and react/jsx-dev-runtime. See the blog post for step-by-step instructions. Note: this will make your plugin incompatible with Grafana versions earlier than 12.3.0.

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

5. Publish an updated version

Once verified, submit a new version of your plugin so it is ready for users when Grafana 13 ships. Ideally only include the react 19 compatibility changes to speed up the review process.

Need help?

If you have any questions or run into issues, please reach out through:

• Blog post with more details
• Migration guide
• Community Forums
• Community Slack - channel #plugin-development