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: false5. 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:
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.jsonlives), run:This will scan your built output and source code for known React 19 breaking changes, including:
propTypeschecks anddefaultPropson function componentscontextTypesandgetChildContext)createFactoryReactDOM.findDomNodeReactDOM.renderandReactDOM.unmountComponentAtNode__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED2. Fix any issues found
__SECRET_INTERNALSissues — these are the most likely cause of plugin loading failures. To resolve them, extend your plugin's webpack config to externalizereact/jsx-runtimeandreact/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:
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-versionworkflow, add the following input to also test against the React 19 preview image: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:
#plugin-development