@grafana/create-plugin 6.3.0-canary.2314.19540598852.0 → 6.3.0-canary.2320.19631436862.0

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

@@ -0,0 +1,81 @@
+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 { addI18nInitialization, createLoadResourcesFile } from './code-generation.js';
+import { updateEslintConfig, addI18nDependency, addSemverDependency, addI18nextCli } from './tooling.js';
+import { checkNeedsBackwardCompatibility, createLocaleFiles } from './utils.js';
+
+/**
+ * I18n addition schema using Valibot
+ * Adds internationalization support to a plugin
+ */
+export const schema = v.object(
+  {
+    locales: v.pipe(
+      v.union([v.string(), v.array(v.string())]),
+      v.transform((input) => {
+        // Handle both string (from CLI) and array (from tests)
+        return typeof input === 'string' ? input.split(',').map((s) => s.trim()) : input;
+      }),
+      v.array(
+        v.pipe(
+          v.string(),
+          v.regex(/^[a-z]{2}-[A-Z]{2}$/, 'Locale must be in format xx-XX (e.g., en-US, es-ES, sv-SE)')
+        ),
+        'Please provide a comma-separated list of all supported locales, e.g., "en-US,es-ES,sv-SE"'
+      ),
+      v.minLength(1, 'Please provide a comma-separated list of all supported locales, e.g., "en-US,es-ES,sv-SE"')
+    ),
+  },
+  'Please provide a comma-separated list of all supported locales, e.g., "en-US,es-ES,sv-SE"'
+);
+
+type I18nOptions = v.InferOutput<typeof schema>;
+
+export default function i18nAddition(context: Context, options: I18nOptions): Context {
+  const { locales } = options;
+
+  additionsDebug('Adding i18n support with locales:', locales);
+
+  // Determine if we need backward compatibility (Grafana < 12.1.0)
+  const needsBackwardCompatibility = checkNeedsBackwardCompatibility(context);
+  additionsDebug('Needs backward compatibility:', needsBackwardCompatibility);
+
+  // 1. Update docker-compose.yaml with feature toggle
+  updateDockerCompose(context);
+
+  // 2. Update plugin.json with languages and grafanaDependency
+  updatePluginJson(context, locales, needsBackwardCompatibility);
+
+  // 3. Create locale folders and files
+  createLocaleFiles(context, locales);
+
+  // 4. Add @grafana/i18n dependency
+  addI18nDependency(context);
+
+  // 5. Add semver dependency for backward compatibility
+  if (needsBackwardCompatibility) {
+    addSemverDependency(context);
+  }
+
+  // 6. Update eslint.config.mjs if needed
+  updateEslintConfig(context);
+
+  // 7. Add i18n initialization to module file
+  addI18nInitialization(context, needsBackwardCompatibility);
+
+  // 8. Create loadResources.ts for backward compatibility
+  if (needsBackwardCompatibility) {
+    createLoadResourcesFile(context);
+  }
+
+  // 9. Add i18next-cli as dev dependency and add script
+  addI18nextCli(context);
+
+  // 10. Create i18next.config.ts
+  createI18nextConfig(context);
+
+  return context;
+}

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

@@ -0,0 +1,146 @@
+import * as recast from 'recast';
+import * as babelParser from 'recast/parsers/babel-ts.js';
+
+import type { Context } from '../../../context.js';
+import { addDependenciesToPackageJson, additionsDebug } from '../../../utils.js';
+
+const { builders } = recast.types;
+
+export function addI18nDependency(context: Context): void {
+  addDependenciesToPackageJson(context, { '@grafana/i18n': '12.2.2' }, {});
+  additionsDebug('Added @grafana/i18n dependency version 12.2.2');
+}
+
+export function addSemverDependency(context: Context): void {
+  // Add semver as regular dependency and @types/semver as dev dependency
+  addDependenciesToPackageJson(context, { semver: '^7.6.0' }, { '@types/semver': '^7.5.0' });
+  additionsDebug('Added semver dependency');
+}
+
+export function addI18nextCli(context: Context): void {
+  // Add i18next-cli as dev dependency
+  addDependenciesToPackageJson(context, {}, { 'i18next-cli': '^1.1.1' });
+
+  // Add i18n-extract script to package.json
+  const packageJsonRaw = context.getFile('package.json');
+  if (!packageJsonRaw) {
+    return;
+  }
+
+  try {
+    const packageJson = JSON.parse(packageJsonRaw);
+
+    if (!packageJson.scripts) {
+      packageJson.scripts = {};
+    }
+
+    // Defensive: only add if not already present
+    if (!packageJson.scripts['i18n-extract']) {
+      packageJson.scripts['i18n-extract'] = 'i18next-cli extract --sync-primary';
+      context.updateFile('package.json', JSON.stringify(packageJson, null, 2));
+      additionsDebug('Added i18n-extract script to package.json');
+    } else {
+      additionsDebug('i18n-extract script already exists, skipping');
+    }
+  } catch (error) {
+    additionsDebug('Error adding i18n-extract script:', error);
+  }
+}
+
+export function updateEslintConfig(context: Context): void {
+  if (!context.doesFileExist('eslint.config.mjs')) {
+    additionsDebug('eslint.config.mjs not found, skipping');
+    return;
+  }
+
+  const eslintConfigRaw = context.getFile('eslint.config.mjs');
+  if (!eslintConfigRaw) {
+    return;
+  }
+
+  // Defensive: check if @grafana/i18n eslint plugin is already configured
+  if (eslintConfigRaw.includes('@grafana/i18n/eslint-plugin')) {
+    additionsDebug('ESLint i18n rule already configured');
+    return;
+  }
+
+  try {
+    const ast = recast.parse(eslintConfigRaw, {
+      parser: babelParser,
+    });
+
+    // Find the import section and add the plugin import
+    const imports = ast.program.body.filter((node: any) => node.type === 'ImportDeclaration');
+    const lastImport = imports[imports.length - 1];
+
+    if (lastImport) {
+      const pluginImport = builders.importDeclaration(
+        [builders.importDefaultSpecifier(builders.identifier('grafanaI18nPlugin'))],
+        builders.literal('@grafana/i18n/eslint-plugin')
+      );
+
+      const lastImportIndex = ast.program.body.indexOf(lastImport);
+      ast.program.body.splice(lastImportIndex + 1, 0, pluginImport);
+    }
+
+    // Find the defineConfig array and add the plugin config
+    recast.visit(ast, {
+      visitCallExpression(path: any) {
+        if (path.node.callee.name === 'defineConfig' && path.node.arguments[0]?.type === 'ArrayExpression') {
+          const configArray = path.node.arguments[0];
+
+          // Add the grafana i18n config object
+          const i18nConfig = builders.objectExpression([
+            builders.property('init', builders.identifier('name'), builders.literal('grafana/i18n-rules')),
+            builders.property(
+              'init',
+              builders.identifier('plugins'),
+              builders.objectExpression([
+                builders.property('init', builders.literal('@grafana/i18n'), builders.identifier('grafanaI18nPlugin')),
+              ])
+            ),
+            builders.property(
+              'init',
+              builders.identifier('rules'),
+              builders.objectExpression([
+                builders.property(
+                  'init',
+                  builders.literal('@grafana/i18n/no-untranslated-strings'),
+                  builders.arrayExpression([
+                    builders.literal('error'),
+                    builders.objectExpression([
+                      builders.property(
+                        'init',
+                        builders.identifier('calleesToIgnore'),
+                        builders.arrayExpression([builders.literal('^css$'), builders.literal('use[A-Z].*')])
+                      ),
+                    ]),
+                  ])
+                ),
+                builders.property(
+                  'init',
+                  builders.literal('@grafana/i18n/no-translation-top-level'),
+                  builders.literal('error')
+                ),
+              ])
+            ),
+          ]);
+
+          configArray.elements.push(i18nConfig);
+        }
+        this.traverse(path);
+      },
+    });
+
+    const output = recast.print(ast, {
+      tabWidth: 2,
+      trailingComma: true,
+      lineTerminator: '\n',
+    }).code;
+
+    context.updateFile('eslint.config.mjs', output);
+    additionsDebug('Updated eslint.config.mjs with i18n linting rules');
+  } catch (error) {
+    additionsDebug('Error updating eslint.config.mjs:', error);
+  }
+}

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

@@ -0,0 +1,60 @@
+import { coerce, gte } from 'semver';
+
+import type { Context } from '../../../context.js';
+import { additionsDebug } from '../../../utils.js';
+
+export function checkNeedsBackwardCompatibility(context: Context): boolean {
+  const pluginJsonRaw = context.getFile('src/plugin.json');
+  if (!pluginJsonRaw) {
+    return false;
+  }
+
+  try {
+    const pluginJson = JSON.parse(pluginJsonRaw);
+    const currentGrafanaDep = pluginJson.dependencies?.grafanaDependency || '>=11.0.0';
+    const minVersion = coerce('12.1.0');
+    const currentVersion = coerce(currentGrafanaDep.replace(/^[><=]+/, ''));
+
+    // If current version is less than 12.1.0, we need backward compatibility
+    if (currentVersion && minVersion && gte(currentVersion, minVersion)) {
+      return false; // Already >= 12.1.0, no backward compat needed
+    }
+    return true; // < 12.1.0, needs backward compat
+  } catch (error) {
+    additionsDebug('Error checking backward compatibility:', error);
+    return true; // Default to backward compat on error
+  }
+}
+
+export function createLocaleFiles(context: Context, locales: string[]): void {
+  // Get plugin ID from plugin.json
+  const pluginJsonRaw = context.getFile('src/plugin.json');
+  if (!pluginJsonRaw) {
+    additionsDebug('Cannot create locale files without plugin.json');
+    return;
+  }
+
+  try {
+    const pluginJson = JSON.parse(pluginJsonRaw);
+    const pluginId = pluginJson.id;
+
+    if (!pluginId) {
+      additionsDebug('No plugin ID found in plugin.json');
+      return;
+    }
+
+    // Create locale files for each locale (defensive: only if not already present)
+    for (const locale of locales) {
+      const localePath = `src/locales/${locale}/${pluginId}.json`;
+
+      if (!context.doesFileExist(localePath)) {
+        context.addFile(localePath, JSON.stringify({}, null, 2));
+        additionsDebug(`Created ${localePath}`);
+      } else {
+        additionsDebug(`${localePath} already exists, skipping`);
+      }
+    }
+  } catch (error) {
+    additionsDebug('Error creating locale files:', error);
+  }
+}

package/templates/panel/.config/AGENTS/instructions.md

@@ -1,83 +0,0 @@
----
-name: panel-plugin-agent-fundamentals
-description: Develops Grafana panel plugins
----
-
-You are an expert Grafana panel plugin developer for this project.
-
-## Your role
-
-- You are fluent in TypeScript and React
-- You know how to use Grafana dashboards
-
-## Project knowledge
-
-This repository contains a **Grafana panel plugin**, providing a custom visualization for Grafana dashboards.
-Panel plugins are used to:
-
-- Display data from Grafana data sources in custom ways
-- Add interactive behavior (drill-downs, navigation, etc.)
-- Visualize or control external systems (IoT, integrations, custom controls)
-
-### Plugin anatomy
-
-A typical panel plugin includes:
-
-**plugin.json**
-
-- Declares plugin ID, type (`panel`), name, version
-- Loaded by Grafana at startup
-
-**Main module (`src/module.ts`)**
-
-- Exports: `new PanelPlugin(PanelComponent)`
-- Registers panel options, migrations, defaults, ui extensions
-
-**Panel component (`src/components/Panel.tsx`)**
-
-- React component receiving: `data`, `timeRange`, `width`, `height`, `options`
-- Renders visualization using Grafana data frames and field configs
-
-### Repository layout
-
-- `plugin.json` — Panel plugin manifest
-- `src/module.ts` — Main plugin entry
-- `src/components/` — Panel React components
-- `src/types.ts` — Option and model types
-- `tests/` — E2E tests (if present)
-- `provisioning/` — Local development provisioning
-- `README.md` — Human documentation
-
-## Coding guidelines
-
-- Use **TypeScript**, functional React components, and idiomatic patterns
-- Use **@grafana/ui**, **@grafana/data**, **@grafana/runtime**
-- Use **`useTheme2()`** for all colors, spacing, typography
-- **Never hardcode** colors, spacing, padding, or font sizes
-- Use **Emotion** + `useStyles2()` + theme tokens for styling
-- Keep layouts responsive (use `width`/`height`)
-- Avoid new dependencies unless necessary + Grafana-compatible
-- Maintain consistent file structure and predictable types
-- Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI.
-
-## Boundaries
-
-You must **NOT**:
-
-- Change plugin ID or plugin type in `plugin.json`
-- Modify anything inside `.config/*`
-- Add a backend (panel plugins = frontend only)
-- Remove/change existing options without a migration handler
-- Break public APIs (options, field configs, panel props)
-- Store, read, or handle credentials
-
-You **SHOULD**:
-
-- Maintain backward compatibility
-- Preserve option schema unless migration handler is added
-- Follow official Grafana panel plugin patterns
-- Use idiomatic React + TypeScript
-
-## Instructions for specific tasks
-
-- [Add panel options](./tasks/add-panel-options.md)

package/templates/panel/.config/AGENTS/tasks/add-panel-options.md

@@ -1,132 +0,0 @@
-# Adding a New Panel Option
-
-Panel options are settings the user configures to change panel behavior.
-
-Always complete **all three steps**:
-
-### **1. Extend the options type**
-
-File: `src/types.ts`
-
-```ts
-export interface SimpleOptions {
-  // existing...
-  myOptionName: MyOptionType;
-}
-```
-
-- Property name must match the builder `path`.
-- Type must match expected editor output.
-
----
-
-### **2. Register the option in `setPanelOptions`**
-
-File: `src/module.ts` inside `setPanelOptions((builder) => { ... })`
-
-Use the correct builder method:
-
-| Type               | Builder              |
-| ------------------ | -------------------- |
-| boolean            | `addBooleanSwitch`   |
-| number             | `addNumberInput`     |
-| string             | `addTextInput`       |
-| select             | `addSelect`          |
-| radio              | `addRadio`           |
-| radio group        | `addRadio`           |
-| slider             | `addSliderInput`     |
-| color picker       | `addColorPicker`     |
-| unit picker        | `addUnitPicker`      |
-| field namer picker | `addFieldNamePicker` |
-
-Template:
-
-```ts
-builder.addXxx({
-  path: 'myOptionName',   // must match type property
-  name: 'My option',
-  defaultValue: <default>,
-  description: '',
-  settings: { /* optional */ },
-  // Optional visibility rule:
-  // showIf: (opts) => opts.someOtherOption,
-});
-```
-
-Rules:
-
-- Every option **must** have a `defaultValue`.
-- Put numeric constraints in `settings` (`min`, `max`, `step`).
-- Use `showIf` for conditional display.
-
----
-
-### **3. Use the option in the panel component**
-
-File: `src/Panel.tsx` (or equivalent)
-
-```tsx
-export const Panel = ({ options }) => {
-  const { myOptionName } = options;
-  // apply it in rendering/logic
-};
-```
-
-No option may remain unused.
-
----
-
-# Quick Editor Recipes
-
-### **Boolean**
-
-```ts
-.addBooleanSwitch({ path: 'flag', name: 'Flag', defaultValue: false })
-```
-
-### **Number**
-
-```ts
-.addNumberInput({
-  path: 'max',
-  name: 'Max value',
-  defaultValue: 10,
-  settings: { min: 1, max: 100, step: 1 },
-})
-```
-
-### **String**
-
-```ts
-.addTextInput({ path: 'label', name: 'Label', defaultValue: '' })
-```
-
-### **Select**
-
-```ts
-.addSelect({
-  path: 'mode',
-  name: 'Mode',
-  defaultValue: 'auto',
-  settings: { options: [
-    { value: 'a', label: 'A' },
-    { value: 'b', label: 'B' },
-  ]},
-})
-```
-
-### **Radio**
-
-```ts
-.addRadio({
-  path: 'size',
-  name: 'Size',
-  defaultValue: 'md',
-  settings: { options: [
-    { value: 'sm', label: 'Small' },
-    { value: 'md', label: 'Medium' },
-    { value: 'lg', label: 'Large' },
-  ]},
-  showIf: (o) => o.showSize,
-})
-```

package/templates/panel/AGENTS.md

@@ -1,10 +0,0 @@
----
-name: panel-plugin-agent
-description: Develops Grafana panel plugins
----
-
-## Project knowledge
-
-This repository contains a **Grafana panel plugin**. Follow the [instructions](./.config/AGENTS/instructions.md) before doing any changes.
-
-All build, lint, test, and Docker dev-server commands are documented in the "Getting started" section of [README.md](./README.md). Prefer running the non-watch versions of these commands.