React 19 Plugin Migration

Migrate Grafana Plugin to React 19

Grafana 13 (April 2026) moves from React 18 to React 19. Incompatible plugins will break. Do not upgrade React to 19 — only make forward-compatible changes.

All changes go in one PR. Execute steps in order. Never manually edit yarn.lock.

Step 1: Detect plugin context

PLUGIN_JSON=$([ -f src/plugin.json ] && echo "src/plugin.json" \
  || ([ -f plugin/src/plugin.json ] && echo "plugin/src/plugin.json" || echo ""))
PKG_JSON=$([ -f package.json ] && echo "package.json" \
  || ([ -f plugin/package.json ] && echo "plugin/package.json" || echo ""))
PLUGIN_ID=$(jq -r '.id' $PLUGIN_JSON 2>/dev/null)
[ -f yarn.lock ] && PM="yarn" || ([ -f pnpm-lock.yaml ] && PM="pnpm" || PM="npm")
CP_VERSION=$(jq -r '.version' .config/.cprc.json 2>/dev/null)
echo "PLUGIN_ID=$PLUGIN_ID  PM=$PM  CP=$CP_VERSION"

If PLUGIN_ID is empty, ask the user for the plugin root path.

Step 2: Scan for compatibility issues

Build the plugin and run the React 19 compatibility scanner:

npm run build 2>&1 | tail -5
npx -y @grafana/react-detect@latest 2>&1

Save the output. It flags:

• jsxRuntimeImport / __SECRET_INTERNALS → Step 4 fixes this
• defaultProps / propTypes / ReactDOM.render → Step 8 (source fixes)
• findDOMNode → Step 6 (dependency bump) or Step 8 (source fix)

If the build fails (plugin hasn't been built before), skip this step and run react-detect after Step 9 instead. If output says "No breaking changes detected", still proceed — jsx-runtime externalization and grafanaDependency bump are always required.

Re-run react-detect after Step 9 to confirm all issues are resolved.

Step 3: Update @grafana/create-plugin

The scaffolding update brings in externals extraction, jest mocks, Docker fixes, and webpack improvements needed for React 19. Always do this before add externalize-jsx-runtime.

Requires a clean git working tree. Create a feature branch first if not already on one.

Run the update

npx @grafana/create-plugin@latest update 2>&1

If yarn install fails with "engine is incompatible"

The update runs an intermediate yarn install without --ignore-engines. Complete it manually:

yarn install --ignore-scripts --ignore-engines 2>&1 | tail -10

Commit the intermediate state and re-run:

git add -A && git commit -m "chore: intermediate create-plugin update" --no-verify
npx @grafana/create-plugin@latest update 2>&1

If ESLint 9 migration (004) fails with a parser error

The auto-migration can generate invalid JS on plugins with complex ESLint configs. Do not skip — commit what succeeded, then complete the ESLint 9 migration manually:

git add -A && git commit -m "chore: update create-plugin (ESLint 9 migration manual)" --no-verify

Then follow the "Complete ESLint 9 migration" section below to finish.

After the update

Always run install and verify:

yarn install --ignore-scripts --ignore-engines 2>&1 | tail -10
cat .config/.cprc.json

Commit if there are changes:

git add -A && git diff --cached --quiet || git commit -m "chore: update create-plugin scaffolding" --no-verify

Step 3b: Complete ESLint 9 migration

The create-plugin update bumps ESLint to v9, which requires flat config (eslint.config.js) instead of .eslintrc. Whether the auto-migration (004) succeeded, partially succeeded, or failed, you must ensure ESLint works before proceeding.

Check the current state

ls eslint.config.js .eslintrc* .config/.eslintrc* 2>/dev/null
npx eslint --version 2>&1

Three scenarios:

A) eslint.config.js exists and yarn lint passes — auto-migration succeeded. Proceed.

B) eslint.config.js exists but yarn lint fails — partial migration. Fix the issues:

yarn lint 2>&1 | head -30

Common fixes:

• Invalid option '--ignore-path' or Invalid option '--ext' → remove those flags from the lint script in package.json. In ESLint v9 flat config, ignores and file matching are configured inside eslint.config.js, not via CLI flags. Update to: eslint --cache .
• Cannot find module 'eslint-plugin-deprecation' → remove the import/reference from eslint.config.js (replaced by @typescript-eslint/no-deprecated)
• Other dead plugin imports → remove them from the config if the package was removed

C) No eslint.config.js exists — auto-migration failed. Create one manually:

ls node_modules/@grafana/eslint-config/flat.js 2>/dev/null

If flat.js exists, create eslint.config.js using it as the base:

import grafanaConfig from '@grafana/eslint-config/flat';

export default [
  ...grafanaConfig,
  {
    ignores: ['**/dist/', '**/node_modules/', '**/.config/', '**/coverage/'],
  },
];

Then migrate any custom rules from the old .eslintrc into additional config objects in the array. After creating the flat config:

1. Update the lint script: "lint": "eslint --cache ."
2. Delete the root .eslintrc (leave .config/.eslintrc — it's scaffolded and harmless)

Verify lint works

yarn lint 2>&1 | tail -20

Fix auto-fixable issues with yarn lint --fix. Commit:

git add -A && git diff --cached --quiet || git commit -m "chore: complete ESLint 9 flat config migration" --no-verify

Step 4: Externalize jsx-runtime

Always use the create-plugin add command. Requires a clean git working tree.

npx @grafana/create-plugin@latest add externalize-jsx-runtime 2>&1

Verify:

grep "jsx-runtime" .config/bundler/externals.ts 2>/dev/null

• Found → commit and proceed.
• Not found → command failed. Only then add externals manually to the root webpack.config.ts:

externals: ['react/jsx-runtime', 'react/jsx-dev-runtime'],

Commit:

git add -A && git diff --cached --quiet || git commit -m "feat: externalize jsx-runtime" --no-verify

Step 5: Bump grafanaDependency

jq -r '.dependencies.grafanaDependency' $PLUGIN_JSON

If not already >=12.3.0, update it. The create-plugin add in Step 3 may have already done this.

Step 6: Bump dependencies