From grafana-app-sdk
Migrates Grafana plugins to React 19 compatibility by updating @grafana/create-plugin scaffolding, bumping grafanaDependency to 12.3.0, externalizing jsx-runtime, running @grafana/react-detect, and fixing issues like SECRET_INTERNALS.
npx claudepluginhub grafana/skills --plugin grafana-app-sdkThis skill uses the workspace's default tool permissions.
Grafana 13 (April 2026) moves from React 18 to React 19. Incompatible plugins will break.
Provides migration patterns for React 19 source files, covering render/hydrate APIs, ref handling, legacy context, defaultProps, string refs, and propTypes notes.
Provides minimum version matrix for React 18.3.1 and React 19 compatibility for core, testing libraries, Apollo, Emotion, Router, Redux. Use for upgrades, peer deps, migrations.
Optimizes Grafana app plugin bundle size using React.lazy, Suspense, and webpack code splitting to shrink module.js and boost initial load performance.
Share bugs, ideas, or general feedback.
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.
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.
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 thisdefaultProps / 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.
@grafana/create-pluginThe 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.
npx @grafana/create-plugin@latest update 2>&1
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
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.
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
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.
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)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:
lint script: "lint": "eslint --cache .".eslintrc (leave .config/.eslintrc — it's scaffolded and harmless)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
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
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
grafanaDependencyjq -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.
grep '"@grafana/faro' $PKG_JSON
| Package | Target |
|---|---|
@grafana/faro-react | ^2.2.3 |
@grafana/faro-web-sdk | ^2.2.3 |
@grafana/faro-web-tracing | ^2.0.0 |
grep '"@grafana/' $PKG_JSON | grep -v faro | grep -v create-plugin
Bump @grafana/data, @grafana/runtime, @grafana/schema, @grafana/ui to ^12.2.0 or later.
Add @grafana/i18n@^12.2.0 if the plugin uses translations or @grafana/scenes requires it.
Bump react and react-dom to ^18.3.0 (surfaces React 19 issues early).
Add @types/react@^18.3.0 and @types/react-dom@^18.3.0 to devDependencies if missing.
Remove from devDependencies if present:
eslint-plugin-deprecation (replaced by @typescript-eslint/no-deprecated)@types/testing-library__jest-dom (replaced by setupTests.d.ts)If yarn install fails with a stale git reference, do not edit yarn.lock. Add a resolutions entry:
"resolutions": {
"<package-name>": "<working-version-or-git-ref>"
}
Then delete yarn.lock and node_modules and reinstall:
rm -rf node_modules yarn.lock
yarn install --ignore-engines 2>&1 | tail -10
@openfeature/web-sdk peer dependency@grafana/runtime depends on @openfeature/react-sdk which has @openfeature/web-sdk as a
peer dependency. Yarn v1 (classic) does not auto-install peer deps.
Check if the plugin uses yarn classic:
yarn --version 2>&1 | head -1
If version starts with 1., check for warnings:
yarn install --ignore-engines 2>&1 | grep "unmet peer dependency.*openfeature/web-sdk"
If warnings are found:
yarn add -D @openfeature/web-sdk @openfeature/core --ignore-engines
Skip condition: Yarn v2+ or npm v7+ (peer deps are auto-installed).
grep -rn "ReactDOM\.render\|ReactDOM\.unmountComponentAtNode\|ReactDOM\.findDOMNode" src/ --include="*.tsx" --include="*.ts"
grep -rn "\.defaultProps\s*=" src/ --include="*.tsx" --include="*.ts"
grep -rn "\.propTypes\s*=" src/ --include="*.tsx" --include="*.ts"
grep -rn "contextTypes\|getChildContext" src/ --include="*.tsx" --include="*.ts"
grep -rn "createFactory" src/ --include="*.tsx" --include="*.ts"
grep -rn "ChangeEvent<HTMLInputElement>" src/ --include="*.tsx" --include="*.ts"
| Pattern | Fix |
|---|---|
ReactDOM.render() | createRoot(container).render(element) |
defaultProps on function components | Move to destructured parameter defaults |
defaultProps on class components | Leave — still works |
propTypes | Remove |
contextTypes / getChildContext | Use React.createContext() + useContext() |
createFactory | Use JSX or createElement() |
ChangeEvent<HTMLInputElement> on checkbox | Change to FormEvent<HTMLInputElement> |
rm -rf node_modules dist
yarn install --ignore-engines 2>&1 | tail -10
yarn build 2>&1 | tail -10
yarn typecheck 2>&1 | tail -10
yarn test --watchAll=false 2>&1 | tail -10
| Error | Fix |
|---|---|
Cannot find module 'react/jsx-runtime' | Step 4 not applied — re-run create-plugin add |
Cannot find module '@openfeature/web-sdk' | Step 7 — yarn add -D @openfeature/web-sdk @openfeature/core |
Can't resolve '@grafana/i18n' | yarn add @grafana/i18n@^12.2.0 |
Cannot read properties of undefined (reading 'ReactCurrentOwner') | Bump @grafana-cloud/* packages — see Step 6 |
aria-label is missing on icon-only Button | Add aria-label prop (newer @grafana/ui requires it) |
Stale git hash in yarn.lock | Add resolutions in package.json, delete lockfile, reinstall |
For detailed known issues (i18n crash, @grafana/schema type breaks, publicPath mismatch), see
references/known-issues.md.
grep -rn "plugin-ci-workflows\|e2e-version" .github/workflows/ 2>/dev/null
plugin-ci-workflows@main or >= 6.0.0 → already tests React 19. No changes needed.plugin-actions/e2e-version → add skip-grafana-react-19-preview-image: false.GRAFANA_VERSION=dev-preview-react19 docker compose up --build.git reset --soft origin/main
git add -A
git commit -m "fix: Prepare plugin for React 19 compatibility"
Commit message body should list: create-plugin version change, ESLint 9 migration, key dependency bumps, and any source code fixes.