@grafana/create-plugin 6.5.0-canary.2320.20227367050.0 → 6.5.0-canary.2320.20262762522.0

package/dist/codemods/additions/additions.js

@@ -1,9 +1,4 @@
 var defaultAdditions = [
-  {
-    name: "example-addition",
-    description: "Adds an example addition to the plugin",
-    scriptPath: import.meta.resolve("./scripts/example-addition.js")
-  },
   {
     name: "i18n",
     description: "Adds internationalization (i18n) support to the plugin",

package/dist/codemods/additions/scripts/i18n/config-updates.js

@@ -1,7 +1,10 @@
 import { coerce, gte } from 'semver';
 import { parseDocument, stringify } from 'yaml';
+import * as recast from 'recast';
+import * as typeScriptParser from 'recast/parsers/typescript.js';
 import { additionsDebug } from '../../../utils.js';
 
+const { builders } = recast.types;
 function updateDockerCompose(context) {
   if (!context.doesFileExist("docker-compose.yaml")) {
     additionsDebug("docker-compose.yaml not found, skipping");
@@ -109,5 +112,159 @@ export default defineConfig({
     additionsDebug("Error creating i18next.config.ts:", error);
   }
 }
+function addI18nextToExternalsArray(externalsArray) {
+  const hasI18next = externalsArray.elements.some((element) => {
+    if (element && (element.type === "Literal" || element.type === "StringLiteral") && typeof element.value === "string") {
+      return element.value === "i18next";
+    }
+    return false;
+  });
+  if (hasI18next) {
+    additionsDebug("'i18next' already in externals array");
+    return false;
+  }
+  let insertIndex = -1;
+  for (let i = 0; i < externalsArray.elements.length; i++) {
+    const element = externalsArray.elements[i];
+    if (element && (element.type === "Literal" || element.type === "StringLiteral") && element.value === "rxjs") {
+      insertIndex = i + 1;
+      break;
+    }
+  }
+  if (insertIndex === -1) {
+    for (let i = externalsArray.elements.length - 1; i >= 0; i--) {
+      const element = externalsArray.elements[i];
+      if (element && element.type !== "FunctionExpression" && element.type !== "ArrowFunctionExpression") {
+        insertIndex = i + 1;
+        break;
+      }
+    }
+    if (insertIndex === -1) {
+      insertIndex = externalsArray.elements.length;
+    }
+  }
+  externalsArray.elements.splice(insertIndex, 0, builders.literal("i18next"));
+  additionsDebug(`Added 'i18next' to externals array at position ${insertIndex}`);
+  return true;
+}
+function ensureI18nextExternal(context) {
+  try {
+    additionsDebug("Checking for externals configuration...");
+    const externalsPath = ".config/bundler/externals.ts";
+    if (context.doesFileExist(externalsPath)) {
+      additionsDebug(`Found ${externalsPath}, checking for i18next...`);
+      const externalsContent = context.getFile(externalsPath);
+      if (externalsContent) {
+        try {
+          const ast = recast.parse(externalsContent, {
+            parser: typeScriptParser
+          });
+          let hasChanges = false;
+          recast.visit(ast, {
+            visitVariableDeclarator(path) {
+              const { node } = path;
+              if (node.id.type === "Identifier" && node.id.name === "externals" && node.init && node.init.type === "ArrayExpression") {
+                additionsDebug("Found externals array in externals.ts");
+                if (addI18nextToExternalsArray(node.init)) {
+                  hasChanges = true;
+                }
+              }
+              return this.traverse(path);
+            }
+          });
+          if (hasChanges) {
+            const output = recast.print(ast, {
+              tabWidth: 2,
+              trailingComma: true,
+              lineTerminator: "\n"
+            });
+            context.updateFile(externalsPath, output.code);
+            additionsDebug(`Updated ${externalsPath} with i18next external`);
+          }
+          return;
+        } catch (error) {
+          additionsDebug(`Error updating ${externalsPath}:`, error);
+        }
+      }
+    }
+    const webpackConfigPath = ".config/webpack/webpack.config.ts";
+    additionsDebug(`Checking for ${webpackConfigPath}...`);
+    if (context.doesFileExist(webpackConfigPath)) {
+      additionsDebug(`Found ${webpackConfigPath}, checking for inline externals...`);
+      const webpackContent = context.getFile(webpackConfigPath);
+      if (webpackContent) {
+        try {
+          const ast = recast.parse(webpackContent, {
+            parser: typeScriptParser
+          });
+          let hasChanges = false;
+          let foundExternals = false;
+          recast.visit(ast, {
+            visitObjectExpression(path) {
+              const { node } = path;
+              const properties = node.properties;
+              if (properties) {
+                for (const prop of properties) {
+                  if (prop && (prop.type === "Property" || prop.type === "ObjectProperty")) {
+                    const key = "key" in prop ? prop.key : null;
+                    const value = "value" in prop ? prop.value : null;
+                    if (key && key.type === "Identifier" && key.name === "externals" && value && value.type === "ArrayExpression") {
+                      foundExternals = true;
+                      additionsDebug("Found externals property in webpack.config.ts");
+                      if (addI18nextToExternalsArray(value)) {
+                        hasChanges = true;
+                      }
+                    }
+                  }
+                }
+              }
+              return this.traverse(path);
+            },
+            visitProperty(path) {
+              const { node } = path;
+              if (node.key && node.key.type === "Identifier" && node.key.name === "externals" && node.value && node.value.type === "ArrayExpression") {
+                if (!foundExternals) {
+                  foundExternals = true;
+                  additionsDebug("Found externals property in webpack.config.ts (via visitProperty)");
+                }
+                if (addI18nextToExternalsArray(node.value)) {
+                  hasChanges = true;
+                }
+              }
+              return this.traverse(path);
+            }
+          });
+          if (!foundExternals) {
+            additionsDebug("No externals property found in webpack.config.ts");
+          }
+          if (hasChanges) {
+            const output = recast.print(ast, {
+              tabWidth: 2,
+              trailingComma: true,
+              lineTerminator: "\n"
+            });
+            context.updateFile(webpackConfigPath, output.code);
+            additionsDebug(`Updated ${webpackConfigPath} with i18next external`);
+          } else if (foundExternals) {
+            additionsDebug("i18next already present in externals, no changes needed");
+          }
+          return;
+        } catch (error) {
+          additionsDebug(`Error updating ${webpackConfigPath}:`, error);
+          additionsDebug(`Error details: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      } else {
+        additionsDebug(`File ${webpackConfigPath} exists but content is empty`);
+      }
+    } else {
+      additionsDebug(`File ${webpackConfigPath} does not exist`);
+    }
+    additionsDebug("No externals configuration found, skipping i18next external check");
+  } catch (error) {
+    additionsDebug(
+      `Unexpected error in ensureI18nextExternal: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
 
-export { createI18nextConfig, updateDockerCompose, updatePluginJson };
+export { createI18nextConfig, ensureI18nextExternal, updateDockerCompose, updatePluginJson };

package/dist/codemods/additions/scripts/i18n/index.js

@@ -1,9 +1,9 @@
 import * as v from 'valibot';
 import { additionsDebug } from '../../../utils.js';
-import { updateDockerCompose, updatePluginJson, createI18nextConfig } from './config-updates.js';
+import { updateDockerCompose, updatePluginJson, createI18nextConfig, ensureI18nextExternal } from './config-updates.js';
 import { addI18nInitialization, createLoadResourcesFile } from './code-generation.js';
 import { addI18nDependency, addSemverDependency, updateEslintConfig, addI18nextCli } from './tooling.js';
-import { checkNeedsBackwardCompatibility, createLocaleFiles } from './utils.js';
+import { checkReactVersion, checkNeedsBackwardCompatibility, createLocaleFiles } from './utils.js';
 
 const schema = v.object(
   {
@@ -27,6 +27,7 @@ const schema = v.object(
 function i18nAddition(context, options) {
   const { locales } = options;
   additionsDebug("Adding i18n support with locales:", locales);
+  checkReactVersion(context);
   const needsBackwardCompatibility = checkNeedsBackwardCompatibility(context);
   additionsDebug("Needs backward compatibility:", needsBackwardCompatibility);
   updateDockerCompose(context);
@@ -43,6 +44,20 @@ function i18nAddition(context, options) {
   }
   addI18nextCli(context);
   createI18nextConfig(context);
+  try {
+    ensureI18nextExternal(context);
+  } catch (error) {
+    additionsDebug(`Error ensuring i18next external: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  console.log("\n\u2705 i18n support has been successfully added to your plugin!\n");
+  console.log("Next steps:");
+  console.log("1. Follow the instructions to translate your source code:");
+  console.log(
+    "   https://grafana.com/developers/plugin-tools/how-to-guides/plugin-internationalization-grafana-11#determine-the-text-to-translate"
+  );
+  console.log("2. Run the i18n-extract script to scan your code for translatable strings:");
+  console.log("   npm run i18n-extract  (or yarn/pnpm run i18n-extract)");
+  console.log("3. Fill in your locale JSON files with translated strings\n");
   return context;
 }
 

package/dist/codemods/additions/scripts/i18n/utils.js

@@ -1,6 +1,33 @@
 import { coerce, gte } from 'semver';
 import { additionsDebug } from '../../../utils.js';
 
+function checkReactVersion(context) {
+  const packageJsonRaw = context.getFile("package.json");
+  if (!packageJsonRaw) {
+    return;
+  }
+  try {
+    const packageJson = JSON.parse(packageJsonRaw);
+    const reactVersion = packageJson.dependencies?.react || packageJson.devDependencies?.react || packageJson.peerDependencies?.react;
+    if (reactVersion) {
+      const reactVersionStr = reactVersion.replace(/[^0-9.]/g, "");
+      const reactVersionCoerced = coerce(reactVersionStr);
+      if (reactVersionCoerced && !gte(reactVersionCoerced, "18.0.0")) {
+        throw new Error(
+          `@grafana/i18n requires React 18 or higher. Your plugin is using React ${reactVersion}.
+
+Please upgrade to React 18+ to use i18n support.
+Update your package.json to use "react": "^18.3.0" and "react-dom": "^18.3.0".`
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("@grafana/i18n requires React")) {
+      throw error;
+    }
+    additionsDebug("Error checking React version:", error);
+  }
+}
 function checkNeedsBackwardCompatibility(context) {
   const pluginJsonRaw = context.getFile("src/plugin.json");
   if (!pluginJsonRaw) {
@@ -47,4 +74,4 @@ function createLocaleFiles(context, locales) {
   }
 }
 
-export { checkNeedsBackwardCompatibility, createLocaleFiles };
+export { checkNeedsBackwardCompatibility, checkReactVersion, createLocaleFiles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "6.5.0-canary.2320.20227367050.0",
+  "version": "6.5.0-canary.2320.20262762522.0",
   "repository": {
     "directory": "packages/create-plugin",
     "url": "https://github.com/grafana/plugin-tools"
@@ -56,5 +56,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "d76c5b7a65c1d44699de403e8692e51e129df9f0"
+  "gitHead": "1df74d43ab143d2868f8dc98703faf6f4b120fa9"
 }

package/src/codemods/additions/additions.ts

@@ -1,11 +1,6 @@
 import { Codemod } from '../types.js';
 
 export default [
-  {
-    name: 'example-addition',
-    description: 'Adds an example addition to the plugin',
-    scriptPath: import.meta.resolve('./scripts/example-addition.js'),
-  },
   {
     name: 'i18n',
     description: 'Adds internationalization (i18n) support to the plugin',

package/src/codemods/additions/scripts/i18n/README.md

@@ -8,6 +8,11 @@ Adds internationalization (i18n) support to a Grafana plugin.
 npx @grafana/create-plugin add i18n --locales <locales>
 ```
 
+## Requirements
+
+- **Grafana >= 11.0.0**: i18n is not supported for Grafana versions prior to 11.0.0. If your plugin's `grafanaDependency` is set to a version < 11.0.0, the script will automatically update it to `>=11.0.0`.
+- **React >= 18**: The `@grafana/i18n` package requires React 18 or higher. If your plugin uses React < 18, the script will exit with an error and prompt you to upgrade.
+
 ## Required Flags
 
 ### `--locales`
@@ -24,6 +29,12 @@ npx @grafana/create-plugin add i18n --locales en-US,es-ES,sv-SE
 
 ## What This Addition Does
 
+**Important:** This script sets up the infrastructure and configuration needed for translations. After running this script, you'll need to:
+
+1. Mark up your code with translation functions (`t()` and `<Trans>`)
+2. Run `npm run i18n-extract` to extract translatable strings
+3. Fill in the locale JSON files with translated strings
+
 This addition configures your plugin for internationalization by:
 
 1. **Updating `docker-compose.yaml`** - Adds the `localizationForPlugins` feature toggle to your local Grafana instance
@@ -39,9 +50,11 @@ This addition configures your plugin for internationalization by:
 
 ## Backward Compatibility
 
+**Note:** i18n is not supported for Grafana versions prior to 11.0.0.
+
 The addition automatically detects your plugin's `grafanaDependency` version:
 
-### Grafana >= 12.1.0 (Modern)
+### Grafana >= 12.1.0
 
 - Sets `grafanaDependency` to `>=12.1.0`
 - Grafana handles loading translations automatically
@@ -49,7 +62,7 @@ The addition automatically detects your plugin's `grafanaDependency` version:
 - No `loadResources.ts` file needed
 - No `semver` dependency needed
 
-### Grafana 11.0.0 - 12.0.x (Backward Compatible)
+### Grafana 11.0.0 - 12.0.x
 
 - Keeps or sets `grafanaDependency` to `>=11.0.0`
 - Plugin handles loading translations
@@ -57,9 +70,9 @@ The addition automatically detects your plugin's `grafanaDependency` version:
 - Adds runtime version check using `semver`
 - Initialization with loaders: `await initPluginTranslations(pluginJson.id, loaders)`
 
-## Running Multiple Times (Idempotent)
+## Running Multiple Times
 
-This addition is **defensive** and can be run multiple times safely. Each operation checks if it's already been done:
+This addition can be run multiple times safely. It uses defensive programming to check if configurations already exist before adding them, preventing duplicates and overwrites:
 
 ### Adding New Locales
 
@@ -75,19 +88,9 @@ npx @grafana/create-plugin add i18n --locales en-US,es-ES,sv-SE
 
 The addition will:
 
-- ✅ Merge new locales into `plugin.json` without duplicates
-- ✅ Create only the new locale files (won't overwrite existing ones)
-- ✅ Skip updating files that already have i18n configured
-
-### What Won't Be Duplicated
-
-- **Locale files**: Existing locale JSON files are never overwritten (preserves your translations)
-- **Dependencies**: Won't re-add dependencies that already exist
-- **ESLint config**: Won't duplicate the i18n plugin import or rules
-- **Module initialization**: Won't add `initPluginTranslations` if it's already present
-- **Support files**: Won't overwrite `i18next.config.ts` or `loadResources.ts` if they exist
-- **npm scripts**: Won't overwrite the `i18n-extract` script if it exists
-- **Docker feature toggle**: Won't duplicate the feature toggle
+- Merge new locales into `plugin.json` without duplicates
+- Create only the new locale files (won't overwrite existing ones)
+- Skip updating files that already have i18n configured
 
 ## Files Created
 
@@ -126,9 +129,7 @@ your-plugin/
 
 After running this addition:
 
-1. **Extract translations**: Run `npm run i18n-extract` to scan your code for translatable strings
-2. **Add translations**: Fill in your locale JSON files with translated strings
-3. **Use in code**: Import and use the translation functions:
+1. **Use in code**: Import and use the translation functions to mark up your code:
 
    ```typescript
    import { t, Trans } from '@grafana/i18n';
@@ -142,6 +143,9 @@ After running this addition:
    </Trans>
    ```
 
+2. **Extract translations**: Run `npm run i18n-extract` to scan your code for translatable strings
+3. **Add translations**: Fill in your locale JSON files with translated strings
+
 ## Debug Output
 
 Enable debug logging to see what the addition is doing:

package/src/codemods/additions/scripts/i18n/config-updates.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from 'vitest';
+
+import { Context } from '../../../context.js';
+import { ensureI18nextExternal, updatePluginJson } from './config-updates.js';
+
+describe('config-updates', () => {
+  describe('ensureI18nextExternal', () => {
+    it('should add i18next to externals array in .config/bundler/externals.ts', () => {
+      const context = new Context('/virtual');
+
+      context.addFile('.config/bundler/externals.ts', `export const externals = ['react', 'react-dom'];`);
+
+      ensureI18nextExternal(context);
+
+      const externalsContent = context.getFile('.config/bundler/externals.ts');
+      expect(externalsContent).toMatch(/["']i18next["']/);
+      expect(externalsContent).toContain("'react'");
+      expect(externalsContent).toContain("'react-dom'");
+    });
+
+    it('should not duplicate i18next if already in externals array', () => {
+      const context = new Context('/virtual');
+
+      const originalExternals = `export const externals = ['react', 'i18next', 'react-dom'];`;
+      context.addFile('.config/bundler/externals.ts', originalExternals);
+
+      ensureI18nextExternal(context);
+
+      const externalsContent = context.getFile('.config/bundler/externals.ts');
+      const i18nextCount = (externalsContent?.match(/["']i18next["']/g) || []).length;
+      expect(i18nextCount).toBe(1);
+    });
+
+    it('should add i18next to externals in .config/webpack/webpack.config.ts (legacy)', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        '.config/webpack/webpack.config.ts',
+        `import { Configuration } from 'webpack';
+export const config: Configuration = {
+  externals: ['react', 'react-dom'],
+};`
+      );
+
+      ensureI18nextExternal(context);
+
+      const webpackConfig = context.getFile('.config/webpack/webpack.config.ts');
+      expect(webpackConfig).toMatch(/["']i18next["']/);
+      expect(webpackConfig).toContain("'react'");
+      expect(webpackConfig).toContain("'react-dom'");
+    });
+
+    it('should handle missing externals configuration gracefully', () => {
+      const context = new Context('/virtual');
+      // No externals.ts or webpack.config.ts
+
+      expect(() => {
+        ensureI18nextExternal(context);
+      }).not.toThrow();
+    });
+
+    it('should prefer .config/bundler/externals.ts over webpack.config.ts', () => {
+      const context = new Context('/virtual');
+
+      context.addFile('.config/bundler/externals.ts', `export const externals = ['react'];`);
+      context.addFile('.config/webpack/webpack.config.ts', `export const config = { externals: ['react-dom'] };`);
+
+      ensureI18nextExternal(context);
+
+      // Should update externals.ts, not webpack.config.ts
+      const externalsContent = context.getFile('.config/bundler/externals.ts');
+      expect(externalsContent).toMatch(/["']i18next["']/);
+
+      const webpackConfig = context.getFile('.config/webpack/webpack.config.ts');
+      expect(webpackConfig).not.toMatch(/["']i18next["']/);
+    });
+  });
+
+  describe('updatePluginJson', () => {
+    it('should auto-update grafanaDependency from < 11.0.0 to >=11.0.0', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          dependencies: {
+            grafanaDependency: '>=10.0.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['en-US'], true);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.dependencies.grafanaDependency).toBe('>=11.0.0');
+      expect(pluginJson.languages).toEqual(['en-US']);
+    });
+
+    it('should keep grafanaDependency >= 11.0.0 unchanged when needsBackwardCompatibility is true', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          dependencies: {
+            grafanaDependency: '>=11.0.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['en-US'], true);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.dependencies.grafanaDependency).toBe('>=11.0.0');
+    });
+
+    it('should update grafanaDependency to >=12.1.0 when needsBackwardCompatibility is false', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          dependencies: {
+            grafanaDependency: '>=11.0.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['en-US'], false);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.dependencies.grafanaDependency).toBe('>=12.1.0');
+    });
+
+    it('should merge locales with existing languages', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          languages: ['en-US'],
+          dependencies: {
+            grafanaDependency: '>=12.1.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['es-ES', 'sv-SE'], false);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.languages).toEqual(['en-US', 'es-ES', 'sv-SE']);
+    });
+
+    it('should not duplicate locales', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          languages: ['en-US', 'es-ES'],
+          dependencies: {
+            grafanaDependency: '>=12.1.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['en-US', 'sv-SE'], false);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.languages).toEqual(['en-US', 'es-ES', 'sv-SE']);
+    });
+
+    it('should not update grafanaDependency if it is already >= target version', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({
+          id: 'test-plugin',
+          type: 'panel',
+          name: 'Test Plugin',
+          dependencies: {
+            grafanaDependency: '>=13.0.0',
+          },
+        })
+      );
+
+      updatePluginJson(context, ['en-US'], false);
+
+      const pluginJson = JSON.parse(context.getFile('src/plugin.json') || '{}');
+      expect(pluginJson.dependencies.grafanaDependency).toBe('>=13.0.0');
+    });
+  });
+});

package/src/codemods/additions/scripts/i18n/config-updates.ts

@@ -1,9 +1,13 @@
 import { coerce, gte } from 'semver';
 import { parseDocument, stringify } from 'yaml';
+import * as recast from 'recast';
+import * as typeScriptParser from 'recast/parsers/typescript.js';
 
 import type { Context } from '../../../context.js';
 import { additionsDebug } from '../../../utils.js';
 
+const { builders } = recast.types;
+
 export function updateDockerCompose(context: Context): void {
   if (!context.doesFileExist('docker-compose.yaml')) {
     additionsDebug('docker-compose.yaml not found, skipping');
@@ -137,3 +141,221 @@ export default defineConfig({
     additionsDebug('Error creating i18next.config.ts:', error);
   }
 }
+
+/**
+ * Adds 'i18next' to an externals array if it's not already present
+ * @returns true if changes were made, false otherwise
+ */
+function addI18nextToExternalsArray(externalsArray: recast.types.namedTypes.ArrayExpression): boolean {
+  // Check if 'i18next' is already in the array
+  const hasI18next = externalsArray.elements.some((element) => {
+    if (
+      element &&
+      (element.type === 'Literal' || element.type === 'StringLiteral') &&
+      typeof element.value === 'string'
+    ) {
+      return element.value === 'i18next';
+    }
+    return false;
+  });
+
+  if (hasI18next) {
+    additionsDebug("'i18next' already in externals array");
+    return false;
+  }
+
+  // Find the position after 'rxjs' to insert 'i18next'
+  let insertIndex = -1;
+  for (let i = 0; i < externalsArray.elements.length; i++) {
+    const element = externalsArray.elements[i];
+    if (element && (element.type === 'Literal' || element.type === 'StringLiteral') && element.value === 'rxjs') {
+      insertIndex = i + 1;
+      break;
+    }
+  }
+
+  // If 'rxjs' not found, append to the end (before the function at the end)
+  if (insertIndex === -1) {
+    // Find the last non-function element
+    for (let i = externalsArray.elements.length - 1; i >= 0; i--) {
+      const element = externalsArray.elements[i];
+      if (element && element.type !== 'FunctionExpression' && element.type !== 'ArrowFunctionExpression') {
+        insertIndex = i + 1;
+        break;
+      }
+    }
+    // If still not found, append at the end
+    if (insertIndex === -1) {
+      insertIndex = externalsArray.elements.length;
+    }
+  }
+
+  // Insert 'i18next' at the found position
+  externalsArray.elements.splice(insertIndex, 0, builders.literal('i18next'));
+  additionsDebug(`Added 'i18next' to externals array at position ${insertIndex}`);
+  return true;
+}
+
+export function ensureI18nextExternal(context: Context): void {
+  try {
+    additionsDebug('Checking for externals configuration...');
+
+    // Try new structure first: .config/bundler/externals.ts
+    const externalsPath = '.config/bundler/externals.ts';
+    if (context.doesFileExist(externalsPath)) {
+      additionsDebug(`Found ${externalsPath}, checking for i18next...`);
+      const externalsContent = context.getFile(externalsPath);
+      if (externalsContent) {
+        try {
+          const ast = recast.parse(externalsContent, {
+            parser: typeScriptParser,
+          });
+
+          let hasChanges = false;
+
+          // Find the externals array
+          recast.visit(ast, {
+            visitVariableDeclarator(path) {
+              const { node } = path;
+
+              if (
+                node.id.type === 'Identifier' &&
+                node.id.name === 'externals' &&
+                node.init &&
+                node.init.type === 'ArrayExpression'
+              ) {
+                additionsDebug('Found externals array in externals.ts');
+                if (addI18nextToExternalsArray(node.init)) {
+                  hasChanges = true;
+                }
+              }
+
+              return this.traverse(path);
+            },
+          });
+
+          // Only update the file if we made changes
+          if (hasChanges) {
+            const output = recast.print(ast, {
+              tabWidth: 2,
+              trailingComma: true,
+              lineTerminator: '\n',
+            });
+            context.updateFile(externalsPath, output.code);
+            additionsDebug(`Updated ${externalsPath} with i18next external`);
+          }
+          return;
+        } catch (error) {
+          additionsDebug(`Error updating ${externalsPath}:`, error);
+        }
+      }
+    }
+
+    // Fall back to legacy structure: .config/webpack/webpack.config.ts with inline externals
+    const webpackConfigPath = '.config/webpack/webpack.config.ts';
+    additionsDebug(`Checking for ${webpackConfigPath}...`);
+    if (context.doesFileExist(webpackConfigPath)) {
+      additionsDebug(`Found ${webpackConfigPath}, checking for inline externals...`);
+      const webpackContent = context.getFile(webpackConfigPath);
+      if (webpackContent) {
+        try {
+          const ast = recast.parse(webpackContent, {
+            parser: typeScriptParser,
+          });
+
+          let hasChanges = false;
+          let foundExternals = false;
+
+          // Find the externals property in the Configuration object
+          // It can be in baseConfig or any variable with an object initializer
+          recast.visit(ast, {
+            visitObjectExpression(path) {
+              const { node } = path;
+              const properties = node.properties;
+
+              if (properties) {
+                for (const prop of properties) {
+                  // Handle both Property and ObjectProperty types
+                  if (prop && (prop.type === 'Property' || prop.type === 'ObjectProperty')) {
+                    const key = 'key' in prop ? prop.key : null;
+                    const value = 'value' in prop ? prop.value : null;
+
+                    if (
+                      key &&
+                      key.type === 'Identifier' &&
+                      key.name === 'externals' &&
+                      value &&
+                      value.type === 'ArrayExpression'
+                    ) {
+                      foundExternals = true;
+                      additionsDebug('Found externals property in webpack.config.ts');
+                      if (addI18nextToExternalsArray(value)) {
+                        hasChanges = true;
+                      }
+                      // Don't break, continue to check all object expressions
+                    }
+                  }
+                }
+              }
+
+              return this.traverse(path);
+            },
+            visitProperty(path) {
+              const { node } = path;
+
+              // Also check properties directly (fallback)
+              if (
+                node.key &&
+                node.key.type === 'Identifier' &&
+                node.key.name === 'externals' &&
+                node.value &&
+                node.value.type === 'ArrayExpression'
+              ) {
+                if (!foundExternals) {
+                  foundExternals = true;
+                  additionsDebug('Found externals property in webpack.config.ts (via visitProperty)');
+                }
+                if (addI18nextToExternalsArray(node.value)) {
+                  hasChanges = true;
+                }
+              }
+
+              return this.traverse(path);
+            },
+          });
+
+          if (!foundExternals) {
+            additionsDebug('No externals property found in webpack.config.ts');
+          }
+
+          // Only update the file if we made changes
+          if (hasChanges) {
+            const output = recast.print(ast, {
+              tabWidth: 2,
+              trailingComma: true,
+              lineTerminator: '\n',
+            });
+            context.updateFile(webpackConfigPath, output.code);
+            additionsDebug(`Updated ${webpackConfigPath} with i18next external`);
+          } else if (foundExternals) {
+            additionsDebug('i18next already present in externals, no changes needed');
+          }
+          return;
+        } catch (error) {
+          additionsDebug(`Error updating ${webpackConfigPath}:`, error);
+          additionsDebug(`Error details: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      } else {
+        additionsDebug(`File ${webpackConfigPath} exists but content is empty`);
+      }
+    } else {
+      additionsDebug(`File ${webpackConfigPath} does not exist`);
+    }
+
+    additionsDebug('No externals configuration found, skipping i18next external check');
+  } catch (error) {
+    additionsDebug(
+      `Unexpected error in ensureI18nextExternal: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}

package/src/codemods/additions/scripts/i18n/index.test.ts

@@ -372,47 +372,6 @@ describe('i18n addition', () => {
     expect(packageJson.scripts['i18n-extract']).toBe('i18next-cli extract --sync-primary');
   });
 
-  it('should not add ESLint config if already present', () => {
-    const context = new Context('/virtual');
-
-    context.addFile(
-      'src/plugin.json',
-      JSON.stringify({
-        id: 'test-plugin',
-        type: 'panel',
-        name: 'Test Plugin',
-        dependencies: {
-          grafanaDependency: '>=12.1.0',
-        },
-      })
-    );
-    context.addFile(
-      'docker-compose.yaml',
-      `services:
-  grafana:
-    environment:
-      FOO: bar`
-    );
-    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
-    context.addFile(
-      'eslint.config.mjs',
-      'import { defineConfig } from "eslint/config";\nimport grafanaI18nPlugin from "@grafana/i18n/eslint-plugin";\nexport default defineConfig([]);'
-    );
-    context.addFile(
-      'src/module.ts',
-      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
-    );
-
-    const result = i18nAddition(context, { locales: ['en-US'] });
-
-    // The ESLint config should remain unchanged
-    const eslintConfig = result.getFile('eslint.config.mjs');
-    expect(eslintConfig).toContain('@grafana/i18n/eslint-plugin');
-    // Should not have duplicate imports or configs
-    const importCount = (eslintConfig?.match(/@grafana\/i18n\/eslint-plugin/g) || []).length;
-    expect(importCount).toBe(1);
-  });
-
   it('should not create locale files if they already exist', () => {
     const context = new Context('/virtual');
 
@@ -712,59 +671,4 @@ export const plugin = new PanelPlugin();`;
     const toggleCount = (dockerCompose?.match(/localizationForPlugins/g) || []).length;
     expect(toggleCount).toBe(1);
   });
-
-  it('should add correct ESLint config with proper rules and options', () => {
-    const context = new Context('/virtual');
-
-    context.addFile(
-      'src/plugin.json',
-      JSON.stringify({
-        id: 'test-plugin',
-        type: 'panel',
-        name: 'Test Plugin',
-        dependencies: {
-          grafanaDependency: '>=12.1.0',
-        },
-      })
-    );
-    context.addFile(
-      'docker-compose.yaml',
-      `services:
-  grafana:
-    environment:
-      FOO: bar`
-    );
-    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
-    context.addFile(
-      'eslint.config.mjs',
-      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
-    );
-    context.addFile(
-      'src/module.ts',
-      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
-    );
-
-    const result = i18nAddition(context, { locales: ['en-US'] });
-
-    const eslintConfig = result.getFile('eslint.config.mjs');
-
-    // Check correct import (recast uses double quotes)
-    expect(eslintConfig).toContain('import grafanaI18nPlugin from "@grafana/i18n/eslint-plugin"');
-
-    // Check plugin registration
-    expect(eslintConfig).toContain('"@grafana/i18n": grafanaI18nPlugin');
-
-    // Check rules are present
-    expect(eslintConfig).toContain('"@grafana/i18n/no-untranslated-strings"');
-    expect(eslintConfig).toContain('"@grafana/i18n/no-translation-top-level"');
-
-    // Check rule configuration
-    expect(eslintConfig).toContain('"error"');
-    expect(eslintConfig).toContain('calleesToIgnore');
-    expect(eslintConfig).toContain('"^css$"');
-    expect(eslintConfig).toContain('"use[A-Z].*"');
-
-    // Check config name
-    expect(eslintConfig).toContain('name: "grafana/i18n-rules"');
-  });
 });

package/src/codemods/additions/scripts/i18n/index.ts

@@ -2,10 +2,10 @@ import * as v from 'valibot';
 
 import type { Context } from '../../../context.js';
 import { additionsDebug } from '../../../utils.js';
-import { updateDockerCompose, updatePluginJson, createI18nextConfig } from './config-updates.js';
+import { updateDockerCompose, updatePluginJson, createI18nextConfig, ensureI18nextExternal } from './config-updates.js';
 import { addI18nInitialization, createLoadResourcesFile } from './code-generation.js';
 import { updateEslintConfig, addI18nDependency, addSemverDependency, addI18nextCli } from './tooling.js';
-import { checkNeedsBackwardCompatibility, createLocaleFiles } from './utils.js';
+import { checkNeedsBackwardCompatibility, createLocaleFiles, checkReactVersion } from './utils.js';
 
 /**
  * I18n addition schema using Valibot
@@ -39,6 +39,9 @@ export default function i18nAddition(context: Context, options: I18nOptions): Co
 
   additionsDebug('Adding i18n support with locales:', locales);
 
+  // Check React version early - @grafana/i18n requires React 18+
+  checkReactVersion(context);
+
   // Determine if we need backward compatibility (Grafana < 12.1.0)
   const needsBackwardCompatibility = checkNeedsBackwardCompatibility(context);
   additionsDebug('Needs backward compatibility:', needsBackwardCompatibility);
@@ -77,5 +80,23 @@ export default function i18nAddition(context: Context, options: I18nOptions): Co
   // 10. Create i18next.config.ts
   createI18nextConfig(context);
 
+  // 11. Ensure i18next is in externals array
+  try {
+    ensureI18nextExternal(context);
+  } catch (error) {
+    additionsDebug(`Error ensuring i18next external: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // Success message with next steps
+  console.log('\n✅ i18n support has been successfully added to your plugin!\n');
+  console.log('Next steps:');
+  console.log('1. Follow the instructions to translate your source code:');
+  console.log(
+    '   https://grafana.com/developers/plugin-tools/how-to-guides/plugin-internationalization-grafana-11#determine-the-text-to-translate'
+  );
+  console.log('2. Run the i18n-extract script to scan your code for translatable strings:');
+  console.log('   npm run i18n-extract  (or yarn/pnpm run i18n-extract)');
+  console.log('3. Fill in your locale JSON files with translated strings\n');
+
   return context;
 }

package/src/codemods/additions/scripts/i18n/tooling.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+
+import { Context } from '../../../context.js';
+import { updateEslintConfig } from './tooling.js';
+
+describe('tooling', () => {
+  describe('updateEslintConfig', () => {
+    it('should add correct ESLint config with proper rules and options', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'eslint.config.mjs',
+        'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+      );
+
+      updateEslintConfig(context);
+
+      const eslintConfig = context.getFile('eslint.config.mjs');
+
+      // Check correct import (recast uses double quotes)
+      expect(eslintConfig).toContain('import grafanaI18nPlugin from "@grafana/i18n/eslint-plugin"');
+
+      // Check plugin registration
+      expect(eslintConfig).toContain('"@grafana/i18n": grafanaI18nPlugin');
+
+      // Check rules are present
+      expect(eslintConfig).toContain('"@grafana/i18n/no-untranslated-strings"');
+      expect(eslintConfig).toContain('"@grafana/i18n/no-translation-top-level"');
+
+      // Check rule configuration
+      expect(eslintConfig).toContain('"error"');
+      expect(eslintConfig).toContain('calleesToIgnore');
+      expect(eslintConfig).toContain('"^css$"');
+      expect(eslintConfig).toContain('"use[A-Z].*"');
+
+      // Check config name
+      expect(eslintConfig).toContain('name: "grafana/i18n-rules"');
+    });
+
+    it('should not add ESLint config if already present', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'eslint.config.mjs',
+        'import { defineConfig } from "eslint/config";\nimport grafanaI18nPlugin from "@grafana/i18n/eslint-plugin";\nexport default defineConfig([]);'
+      );
+
+      const originalContent = context.getFile('eslint.config.mjs');
+
+      updateEslintConfig(context);
+
+      // The ESLint config should remain unchanged
+      const eslintConfig = context.getFile('eslint.config.mjs');
+      expect(eslintConfig).toBe(originalContent);
+      expect(eslintConfig).toContain('@grafana/i18n/eslint-plugin');
+      // Should not have duplicate imports or configs
+      const importCount = (eslintConfig?.match(/@grafana\/i18n\/eslint-plugin/g) || []).length;
+      expect(importCount).toBe(1);
+    });
+
+    it('should handle missing eslint.config.mjs gracefully', () => {
+      const context = new Context('/virtual');
+      // No eslint.config.mjs file
+
+      expect(() => {
+        updateEslintConfig(context);
+      }).not.toThrow();
+    });
+
+    it('should handle empty eslint.config.mjs gracefully', () => {
+      const context = new Context('/virtual');
+
+      context.addFile('eslint.config.mjs', '');
+
+      expect(() => {
+        updateEslintConfig(context);
+      }).not.toThrow();
+    });
+  });
+});

package/src/codemods/additions/scripts/i18n/utils.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+
+import { Context } from '../../../context.js';
+import { checkReactVersion } from './utils.js';
+
+describe('utils', () => {
+  describe('checkReactVersion', () => {
+    it('should throw error if React < 18 in dependencies', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          dependencies: {
+            react: '^17.0.2',
+            'react-dom': '^17.0.2',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).toThrow('@grafana/i18n requires React 18 or higher');
+    });
+
+    it('should throw error if React 17 in devDependencies', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          devDependencies: {
+            react: '^17.0.2',
+            'react-dom': '^17.0.2',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).toThrow('@grafana/i18n requires React 18 or higher');
+    });
+
+    it('should throw error if React 17 in peerDependencies', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          peerDependencies: {
+            react: '^17.0.2',
+            'react-dom': '^17.0.2',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).toThrow('@grafana/i18n requires React 18 or higher');
+    });
+
+    it('should continue if React >= 18', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          dependencies: {
+            react: '^18.3.0',
+            'react-dom': '^18.3.0',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).not.toThrow();
+    });
+
+    it('should continue if React version cannot be determined (no package.json)', () => {
+      const context = new Context('/virtual');
+      // No package.json file
+
+      expect(() => {
+        checkReactVersion(context);
+      }).not.toThrow();
+    });
+
+    it('should continue if React version cannot be determined (no React dependency)', () => {
+      const context = new Context('/virtual');
+
+      context.addFile('package.json', JSON.stringify({})); // No React dependency
+
+      expect(() => {
+        checkReactVersion(context);
+      }).not.toThrow();
+    });
+
+    it('should handle version ranges correctly', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          dependencies: {
+            react: '~18.1.0',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).not.toThrow();
+    });
+
+    it('should handle React 19', () => {
+      const context = new Context('/virtual');
+
+      context.addFile(
+        'package.json',
+        JSON.stringify({
+          dependencies: {
+            react: '^19.0.0',
+          },
+        })
+      );
+
+      expect(() => {
+        checkReactVersion(context);
+      }).not.toThrow();
+    });
+  });
+});

package/src/codemods/additions/scripts/i18n/utils.ts

@@ -3,6 +3,43 @@ import { coerce, gte } from 'semver';
 import type { Context } from '../../../context.js';
 import { additionsDebug } from '../../../utils.js';
 
+/**
+ * Checks if React version is >= 18
+ * @throws Error if React < 18 (since @grafana/i18n requires React 18+)
+ */
+export function checkReactVersion(context: Context): void {
+  const packageJsonRaw = context.getFile('package.json');
+  if (!packageJsonRaw) {
+    return;
+  }
+
+  try {
+    const packageJson = JSON.parse(packageJsonRaw);
+    const reactVersion =
+      packageJson.dependencies?.react || packageJson.devDependencies?.react || packageJson.peerDependencies?.react;
+
+    if (reactVersion) {
+      const reactVersionStr = reactVersion.replace(/[^0-9.]/g, '');
+      const reactVersionCoerced = coerce(reactVersionStr);
+
+      if (reactVersionCoerced && !gte(reactVersionCoerced, '18.0.0')) {
+        throw new Error(
+          `@grafana/i18n requires React 18 or higher. Your plugin is using React ${reactVersion}.\n\n` +
+            `Please upgrade to React 18+ to use i18n support.\n` +
+            `Update your package.json to use "react": "^18.3.0" and "react-dom": "^18.3.0".`
+        );
+      }
+    }
+  } catch (error) {
+    // If it's our version check error, re-throw it
+    if (error instanceof Error && error.message.includes('@grafana/i18n requires React')) {
+      throw error;
+    }
+    // Otherwise, just log and continue (can't determine React version)
+    additionsDebug('Error checking React version:', error);
+  }
+}
+
 export function checkNeedsBackwardCompatibility(context: Context): boolean {
   const pluginJsonRaw = context.getFile('src/plugin.json');
   if (!pluginJsonRaw) {