React 19 is coming to Grafana: what plugin developers need to know
As part of the upcoming Grafana 13 release in April, we will be updating to React 19, the latest major version of the frontend library for building user interfaces. Grafana uses React as the core technology for its frontend UI and its vibrant ecosystem of plugins. This update ensures we stay aligned with the broader React ecosystem, and allows us to take advantage of ongoing performance enhancements and new functionality provided by React APIs.
We want to start by saying thank you to our growing community of plugin developers. Your work is a huge part of what makes Grafana so powerful, and we recognize that upgrades like this can require some time and attention on your part. For most Grafana plugins, this update will only require minor code changes and a dependency audit to ensure compatibility with React 19, but we’d like to offer some guidance to make the process as smooth as possible for our developer community.
Here’s a look at how, exactly, Grafana plugins will be impacted by the upcoming React 19 update, how to perform a dependency audit for your plugin, and how to address some common challenges that might come up along the way.
Why update React?
React 19 was released in December 2024, delivering new features and performance improvements to the open source frontend community. As a result, React library authors have started to discontinue support for React 18, reflecting the community's adoption of the new version.
If Grafana does not keep React updated, the frontend code and its React dependencies risk becoming outdated. Prolonging the React update increases the likelihood of Grafana being affected by performance issues, bugs, or vulnerabilities that have been addressed in React 19 or newer versions of React dependencies.
How does this update impact plugins?
React version in Grafana plugins
Grafana shares a single React instance with all loaded plugins at runtime. This means updating the React version in your plugin's package.json file will not change the runtime version. Instead, the goal is to align to Grafana’s runtime and focus on forward-compatible code.
Important: Do not attempt to force a different React version or bundle React. Pinning a different version locally will result in a test environment that is inconsistent with the Grafana runtime environment.
React 19 breaking changes
React 19 introduces the following breaking changes that may affect the functionality of plugins:
- Removal of
propTypeschecks anddefaultPropson function components - Removal of legacy context API (
contextTypesandgetChildContext) - Removal of string refs
- Removal of
createFactory - Removal of
ReactDOM.findDomNode - Removal of
ReactDOM.renderandReactDOM.unmountComponentAtNode - Renaming of internal React API
__SECRET_INTERNALS_DO_NOT_USE
A full list of React 19 breaking changes can be found here.
Ecosystem risk
Libraries that depend on React internals can also block upgrades. We have already replaced one such dependency (rc-time-picker) in the Grafana codebase.
How to know if your plugin is impacted
To try to make this process as smooth as possible, we’ve created the @grafana/react-detect tool to help you understand how this update impacts your plugin. This tool will scan your plugin’s built JavaScript files and source code to pinpoint potential compatibility issues. Simply run the following commands from the root of your plugin (where the package.json file lives):
npm run buildnpx -y @grafana/react-detect@latest
The output from the CLI tool will help identify locations in your source code or dependencies that use React features that might be affected by the breaking changes in React 19.
Note: The CLI tool can create false positives, particularly if your source code or a dependency is supporting multiple versions of React. It’s meant to be a first step in identifying where incompatible code may live.
React-detect will print out various messages related to any breaking changes it finds. We recommend following its suggestions and links to address any highlighted issues. As you start to address issues with your plugin, make sure to run npm run build if you want to re-run the react-detect CLI.
Below are examples of the types of output you can expect from the CLI tool.
No React 19 breaking changes detected
Amazing! This means your plugin’s source code and dependency audit didn’t surface any issues with React 19 breaking changes. Even so, we strongly suggest that you follow the recommended Next steps to check that your plugin loads and functions correctly with React 19.
React 19 breaking changes detected: source code issues
This CLI output means there are source code issues that require some minor adjustments to fix. The output will give a breakdown of each issue, along with a short explanation of how to start fixing it and a link to the React 19 upgrade guide, which gives more detailed information on how to resolve issues.
React 19 breaking changes detected: dependency issues
Dependency issues are a little more complicated to fix, as you likely don’t own the source code. The CLI output will list each dependency along with a summary of all issues that were found. We recommend the following:
- Make sure your plugin is using the latest version of any dependency that is flagged.
- Check the GitHub repos for each dependency to confirm they support React 19.
If the dependency doesn’t support React 19, look for a fork or a replacement of the original. If the dependency does support React 19, the react-detect CLI is likely flagging a false positive where the library is supporting multiple versions of React
The __SECRET_INTERNALS issue
We believe __SECRET_INTERNALS APIs will be the most likely cause of plugin loading issues. These are internal React APIs that are not intended for direct use, but some React dependencies and the react/jsx-runtime still rely on them.
In React 19, these internals were renamed, which means dependencies that expect the old name may fail or crash at runtime. Plugins affected by this will need to update or replace dependencies that rely on these internals, or ideally remove that usage entirely.
To solve this issue, you will need to extend the plugin’s webpack config. Doing this will make your plugin incompatible with versions of Grafana earlier than 12.3.0.
1. Create a webpack.config.ts file in the root of your plugin’s repo
2. Add the following code to it:
import type { Configuration } from 'webpack';
import { merge } from 'webpack-merge';
import grafanaConfig, { Env } from './.config/webpack/webpack.config';
const config = async (env: Env): Promise<Configuration> => {
const baseConfig = await grafanaConfig(env);
return merge(baseConfig, {
externals: ['react/jsx-runtime', 'react/jsx-dev-runtime'],
});
};
export default config;3. Update the plugin’s package.json to use the new webpack config:
"scripts": {
"build": "webpack -c ./webpack.config.ts --env production",
"dev": "webpack -w -c ./webpack.config.ts --env development",
}4. Change the grafanaDependency in src/plugin.json to >=12.3.0 to signal to plugin users that it no longer supports older versions of Grafana.
Verify your fixes locally
To help simplify the transition to a React 19-compatible plugin, we’ve also created a developer preview of Grafana that uses React 19. This is published as a publicly available Docker image that, thanks to the create-plugin Docker development environment, can be quickly spun up for manual testing. You can run it locally from your plugin’s root directory with:
GRAFANA_VERSION=dev-preview-react19 GRAFANA_IMAGE=grafana docker compose up --build
Once running, we suggest navigating your plugin's features to check that everything behaves as expected. If you have end-to-end (e2e) tests, please run these against the dev-preview-react19 image to help identify any problems.
Once you’re confident your plugin is forward-compatible, you’ll want to check that it still maintains current compatibility. To do this, verify that it continues to work in a build of Grafana that uses React 18. If you have questions or are looking for support, please reach out in our Community Forums or Community Slack.
Verify your fixes in your CI pipelines
To make sure your plugin stays compatible with multiple Grafana versions that include React 19, we recommend using the e2e testing workflow that automatically runs your e2e tests against multiple Grafana versions.
If you are already using the e2e testing workflow (it is usually scaffolded by default), you only need to change one input parameter and point it to the right version of plugin/actions/e2e-version workflows.
Change from:
- name: Resolve Grafana E2E versions
id: resolve-versions
uses: grafana/plugin-actions/e2e-version@e2e-version/v1.1.2To:
- name: Resolve Grafana E2E versions
id: resolve-versions
uses: grafana/plugin-actions/e2e-version@e2e-version/v1.1.3
with:
skip-grafana-react-19-preview-image: false # add this input parameterNext steps and how to learn more
Once you’ve verified your plugin is working with React 19, submitting a new version of your plugin will help us make sure it’s ready for users when Grafana 13 is released.
Lastly, we truly appreciate all your efforts to keep your plugins compatible and reliable. Your contributions are a critical part of the overall Grafana ecosystem. If you have any questions or need help along the way, please don’t hesitate to reach out in our Community Forums or Community Slack.
