@grafana/create-plugin 6.2.0-canary.2314.19503588692.0 → 6.2.0-canary.2314.19529376890.0

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

@@ -1,66 +1,88 @@
-## Project overview
+# Project overview
 
-This repository contains a Grafana panel plugin, which adds a custom visualization that can be used in Grafana dashboards. Panel plugins are useful when you want to:
+This repository contains a **Grafana panel plugin**, providing a custom visualization for Grafana dashboards.
+Panel plugins are used to:
 
-- Present data from Grafana data source queries in a new or specialized way
-- Add custom interactivity, such as navigation or drill-downs
-- Visualize or control external systems (for example, IoT devices or custom integrations)
+- 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)
 
-### High-level anatomy of a Grafana panel plugin
+---
 
-A typical panel plugin has:
+# Plugin anatomy
 
-- A plugin **manifest** (`plugin.json`)
-  - Declares plugin ID, type (`panel`), name, version, and metadata
-  - Picked up by Grafana during boot time to register plugin.
+A typical panel plugin includes:
 
-- A **main module** (usually `src/module.ts` or `src/module.tsx`)
-  - Calls `new PanelPlugin(PanelComponent)` from `@grafana/data` and expose the instance from the module.
-  - Optionally wires in the options editor, panel migration handler, and panel defaults
+## **plugin.json**
 
-- A panel React component (e.g. `src/components/Panel.tsx`)
-  - Renders the visualization
-  - Receives props such as `data`, `timeRange`, `width`, `height`, and `options`
-  - Works with Grafana data frames and field configuration APIs to read query results and settings.
+- Declares plugin ID, type (`panel`), name, version
+- Loaded by Grafana at startup
 
-## Goals for AI coding agents
+## **Main module (`src/module.ts`)**
 
-When working on this project, AI agents should:
+- Exports: `new PanelPlugin(PanelComponent)`
+- Registers panel options, migrations, defaults, extensions (links, components)
 
-- Maintain the existing options schema unless a proper migration handler is implemented
-- Follow idiomatic React and TypeScript practices consistent with Grafana’s official example plugins
-- Treat AGENTS.md as the authoritative source. If anything in .config/AGENTS conflicts with this file, follow the instructions in AGENTS.md
+## **Panel component (`src/components/Panel.tsx`)**
 
-## Repository layout (typical)
+- React component receiving: `data`, `timeRange`, `width`, `height`, `options`
+- Renders visualization using Grafana data frames and field configs
 
-- `plugin.json` – Grafana plugin manifest (type: `panel`)
-- `src/module.ts` – main plugin entry point (creates `PanelPlugin`)
-- `src/components` – React components for the panel
-- `src/types.ts` – TypeScript types for panel options and internal models
-- `tests/` – End-to-end tests (if configured)
-- `provisioning/` - Provisioning files used in the local development environment.
-- `README.md` – Human-facing project documentation
+---
 
-## Coding guidelines
+# Agent goals
 
-- Use **TypeScript** for all plugin code.
-- Prefer **functional React components** and hooks.
-- Use **Grafana UI components** (`@grafana/ui`) and **Grafana data APIs** (`@grafana/data`) or **Grafana runtime APIs** (`@grafana/runtime`) instead of custom UI or data abstractions whenever possible.
-- Keep the panel responsive:
-  - Respect `width` and `height` props.
-  - Avoid fixed layout sizes that break in narrow panels or large screens.
-- Avoid introducing new dependencies unless:
-  - They’re necessary
-  - They’re compatible with Grafana’s frontend environment and plugin guidelines
-- If custom styling is needed, please using `Emotion`.
+Agents must:
 
-## Safety & constraints for agents
+- Preserve the existing options schema unless adding a migration handler
+- Follow idiomatic React + TypeScript patterns used in official Grafana examples
+- Treat **`AGENTS.md` as the authoritative source** over `.config/AGENTS/*`
 
-- Do **not** change `plugin.json` IDs or plugin type.
-- Do **not** change anything in the `.config` folder.
-- Do **not** add a backend to this plugin. A panel plugin is a frontend only plugin.
-- Do **not** remove or break existing option fields without:
-  - Adding a migration handler, or
-  - Updating all usages and tests accordingly.
-- Keep changes to public interfaces (options, field configs, panel props) backwards compatible where possible.
-- When in doubt, mirror patterns from Grafana’s official panel plugin examples and docs.
+---
+
+# 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** and **functional React components**
+- Use **@grafana/ui**, **@grafana/data**, **@grafana/runtime**
+- Respect `width` and `height`; keep layout responsive
+- Avoid unnecessary dependencies; ensure Grafana compatibility
+- Use useTheme2() from @grafana/ui for visual tokens
+- Avoid to hardcode colors, spacing, padding, or font sizes
+- Follow existing file structure
+- Keep code typed and predictable
+
+---
+
+# Safety & constraints
+
+Agents must **not**:
+
+- Change plugin IDs or plugin type in `plugin.json`
+- Modify anything under `.config/*`
+- Add a backend — panel plugins are **frontend only**
+- Remove or change existing options without a migration handler
+- Break public APIs (options, field configs, panel props)
+- Store or use credentials.
+
+Agents **should**:
+
+- Keep the plugin backward compatible
+- Mirror patterns from Grafana’s official panel plugin examples
+
+---
+
+# How-to
+
+- [How-to add panel options](./howto/add-panel-options.md)

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

@@ -0,0 +1,130 @@
+# Adding a New Panel Option
+
+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/dist/migrations/manager.js

@@ -1,58 +0,0 @@
-import { gte, satisfies } from 'semver';
-import { Context } from './context.js';
-import defaultMigrations from './migrations.js';
-import { migrationsDebug, formatFiles, flushChanges, printChanges, installNPMDependencies } from './utils.js';
-import { gitCommitNoVerify } from '../utils/utils.git.js';
-import { setRootConfig } from '../utils/utils.config.js';
-import { output } from '../utils/utils.console.js';
-import { CURRENT_APP_VERSION } from '../utils/utils.version.js';
-
-function getMigrationsToRun(fromVersion, toVersion, migrations = defaultMigrations.migrations) {
-  const semverRange = `${fromVersion} - ${toVersion}`;
-  const migrationsToRun = Object.entries(migrations).sort((a, b) => {
-    return gte(a[1].version, b[1].version) ? 1 : -1;
-  }).reduce((acc, [key, meta]) => {
-    if (satisfies(meta.version, semverRange)) {
-      acc[key] = meta;
-    }
-    return acc;
-  }, {});
-  return migrationsToRun;
-}
-async function runMigrations(migrations, options = {}) {
-  const basePath = process.cwd();
-  const migrationList = Object.entries(migrations).map(
-    ([key, migrationMeta]) => `${key} (${migrationMeta.description})`
-  );
-  const migrationListBody = migrationList.length > 0 ? output.bulletList(migrationList) : ["No migrations to run."];
-  output.log({ title: "Running the following migrations:", body: migrationListBody });
-  for (const [key, migration] of Object.entries(migrations)) {
-    try {
-      const context = await runMigration(migration, new Context(basePath));
-      const shouldCommit = options.commitEachMigration && context.hasChanges();
-      migrationsDebug(`context for "${key} (${migration.migrationScript})":`);
-      migrationsDebug("%O", context.listChanges());
-      await formatFiles(context);
-      flushChanges(context);
-      printChanges(context, key, migration);
-      installNPMDependencies(context);
-      if (shouldCommit) {
-        await gitCommitNoVerify(`chore: run create-plugin migration - ${key} (${migration.migrationScript})`);
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(`Error running migration "${key} (${migration.migrationScript})": ${error.message}`);
-      }
-    }
-  }
-  setRootConfig({ version: CURRENT_APP_VERSION });
-  if (options.commitEachMigration) {
-    await gitCommitNoVerify(`chore: update .config/.cprc.json to version ${CURRENT_APP_VERSION}.`);
-  }
-}
-async function runMigration(migration, context) {
-  const module = await import(migration.migrationScript);
-  return module.default(context);
-}
-
-export { getMigrationsToRun, runMigration, runMigrations };

package/dist/migrations/migrations.js

@@ -1,43 +0,0 @@
-import { LEGACY_UPDATE_CUTOFF_VERSION } from '../constants.js';
-
-var defaultMigrations = {
-  migrations: {
-    "001-update-grafana-compose-extend": {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: "Update ./docker-compose.yaml to extend from ./.config/docker-compose-base.yaml.",
-      migrationScript: "./scripts/001-update-grafana-compose-extend.js"
-    },
-    "002-update-is-compatible-workflow": {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: "Update ./.github/workflows/is-compatible.yml to use is-compatible github action instead of calling levitate directly",
-      migrationScript: "./scripts/002-update-is-compatible-workflow.js"
-    },
-    "003-update-eslint-deprecation-rule": {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: "Replace deprecated eslint-plugin-deprecation with @typescript-eslint/no-deprecated rule.",
-      migrationScript: "./scripts/003-update-eslint-deprecation-rule.js"
-    },
-    "004-eslint9-flat-config": {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: "Migrate eslint config to flat config format and update devDependencies to latest versions.",
-      migrationScript: "./scripts/004-eslint9-flat-config.js"
-    },
-    "005-react-18-3": {
-      version: "6.1.9",
-      description: "Update React and ReactDOM 18.x versions to ^18.3.0 to surface React 19 compatibility issues.",
-      migrationScript: "./scripts/005-react-18-3.js"
-    },
-    "006-webpack-nested-fix": {
-      version: "6.1.11",
-      description: "Fix webpack variable replacement in nested plugins files.",
-      migrationScript: "./scripts/006-webpack-nested-fix.js"
-    },
-    "007-remove-testing-library-types": {
-      version: "6.1.13",
-      description: "Add setupTests.d.ts for @testing-library/jest-dom types and remove @types/testing-library__jest-dom npm package.",
-      migrationScript: "./scripts/007-remove-testing-library-types.js"
-    }
-  }
-};
-
-export { defaultMigrations as default };

package/dist/migrations/scripts/example-migration.js

@@ -1,25 +0,0 @@
-function migrate(context) {
-  const rawPkgJson = context.getFile("./package.json") ?? "{}";
-  const packageJson = JSON.parse(rawPkgJson);
-  if (packageJson.scripts && packageJson.scripts.build) {
-    const buildScript = packageJson.scripts.build;
-    const pattern = /(webpack.+-c\s.+\.ts)\s(.+)/;
-    if (pattern.test(buildScript) && !buildScript.includes("--profile")) {
-      packageJson.scripts.build = buildScript.replace(pattern, `$1 --profile $2`);
-    }
-    context.updateFile("./package.json", JSON.stringify(packageJson, null, 2));
-  }
-  if (context.doesFileExist("./src/README.md")) {
-    context.deleteFile("./src/README.md");
-  }
-  if (!context.doesFileExist("./src/foo.json")) {
-    context.addFile("./src/foo.json", JSON.stringify({ foo: "bar" }));
-  }
-  if (context.doesFileExist(".eslintrc")) {
-    context.renameFile(".eslintrc", ".eslint.config.json");
-  }
-  context.readDir("./src");
-  return context;
-}
-
-export { migrate as default };

package/src/migrations/fixtures/migrations.ts

@@ -1,19 +0,0 @@
-export default {
-  migrations: {
-    'migration-key1': {
-      version: '5.0.0',
-      description: 'Update project to use new cache directory',
-      migrationScript: './5-0-0-cache-directory.js',
-    },
-    'migration-key2': {
-      version: '5.4.0',
-      description: 'Update project to use new cache directory',
-      migrationScript: './5-4-0-cache-directory.js',
-    },
-    'migration-key3': {
-      version: '6.0.0',
-      description: 'Update project to use new cache directory',
-      migrationScript: './5-4-0-cache-directory.js',
-    },
-  },
-};

package/src/migrations/manager.ts

@@ -1,82 +0,0 @@
-import { satisfies, gte } from 'semver';
-import { Context } from './context.js';
-import defaultMigrations, { MigrationMeta } from './migrations.js';
-import { flushChanges, printChanges, migrationsDebug, formatFiles, installNPMDependencies } from './utils.js';
-import { gitCommitNoVerify } from '../utils/utils.git.js';
-import { setRootConfig } from '../utils/utils.config.js';
-import { output } from '../utils/utils.console.js';
-import { CURRENT_APP_VERSION } from '../utils/utils.version.js';
-
-export type MigrationFn = (context: Context) => Context | Promise<Context>;
-
-export function getMigrationsToRun(
-  fromVersion: string,
-  toVersion: string,
-  migrations: Record<string, MigrationMeta> = defaultMigrations.migrations
-): Record<string, MigrationMeta> {
-  const semverRange = `${fromVersion} - ${toVersion}`;
-
-  const migrationsToRun = Object.entries(migrations)
-    .sort((a, b) => {
-      return gte(a[1].version, b[1].version) ? 1 : -1;
-    })
-    .reduce<Record<string, MigrationMeta>>((acc, [key, meta]) => {
-      if (satisfies(meta.version, semverRange)) {
-        acc[key] = meta;
-      }
-      return acc;
-    }, {});
-
-  return migrationsToRun;
-}
-
-type RunMigrationsOptions = {
-  commitEachMigration?: boolean;
-};
-
-export async function runMigrations(migrations: Record<string, MigrationMeta>, options: RunMigrationsOptions = {}) {
-  const basePath = process.cwd();
-  const migrationList = Object.entries(migrations).map(
-    ([key, migrationMeta]) => `${key} (${migrationMeta.description})`
-  );
-
-  const migrationListBody = migrationList.length > 0 ? output.bulletList(migrationList) : ['No migrations to run.'];
-
-  output.log({ title: 'Running the following migrations:', body: migrationListBody });
-
-  for (const [key, migration] of Object.entries(migrations)) {
-    try {
-      const context = await runMigration(migration, new Context(basePath));
-      const shouldCommit = options.commitEachMigration && context.hasChanges();
-
-      migrationsDebug(`context for "${key} (${migration.migrationScript})":`);
-      migrationsDebug('%O', context.listChanges());
-
-      await formatFiles(context);
-      flushChanges(context);
-      printChanges(context, key, migration);
-
-      installNPMDependencies(context);
-
-      if (shouldCommit) {
-        await gitCommitNoVerify(`chore: run create-plugin migration - ${key} (${migration.migrationScript})`);
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(`Error running migration "${key} (${migration.migrationScript})": ${error.message}`);
-      }
-    }
-  }
-
-  setRootConfig({ version: CURRENT_APP_VERSION });
-
-  if (options.commitEachMigration) {
-    await gitCommitNoVerify(`chore: update .config/.cprc.json to version ${CURRENT_APP_VERSION}.`);
-  }
-}
-
-export async function runMigration(migration: MigrationMeta, context: Context): Promise<Context> {
-  const module: { default: MigrationFn } = await import(migration.migrationScript);
-
-  return module.default(context);
-}

package/src/migrations/migrations.test.ts

@@ -1,16 +0,0 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import defaultMigrations from './migrations.js';
-
-describe('migrations json', () => {
-  // As migration scripts are imported dynamically when update is run we assert the path is valid
-  // Vitest 4 reimplemented it's workers which caused the previous dynamic import tests to fail.
-  // This test now only asserts that the source file exists.
-  Object.entries(defaultMigrations.migrations).forEach(([key, migration]) => {
-    it(`should have a valid migration script path for ${key}`, () => {
-      const migrationPathString = migration.migrationScript.replace('.js', '.ts');
-      const path = join(__dirname, migrationPathString);
-      expect(existsSync(path)).toBe(true);
-    });
-  });
-});

package/src/migrations/migrations.ts

@@ -1,55 +0,0 @@
-import { LEGACY_UPDATE_CUTOFF_VERSION } from '../constants.js';
-
-export type MigrationMeta = {
-  version: string;
-  description: string;
-  migrationScript: string;
-};
-
-type Migrations = {
-  migrations: Record<string, MigrationMeta>;
-};
-
-// Do not use LEGACY_UPDATE_CUTOFF_VERSION for new migrations. It was used to force migrations to run
-// for those written before the switch to updates as migrations.
-export default {
-  migrations: {
-    '001-update-grafana-compose-extend': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Update ./docker-compose.yaml to extend from ./.config/docker-compose-base.yaml.',
-      migrationScript: './scripts/001-update-grafana-compose-extend.js',
-    },
-    '002-update-is-compatible-workflow': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description:
-        'Update ./.github/workflows/is-compatible.yml to use is-compatible github action instead of calling levitate directly',
-      migrationScript: './scripts/002-update-is-compatible-workflow.js',
-    },
-    '003-update-eslint-deprecation-rule': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Replace deprecated eslint-plugin-deprecation with @typescript-eslint/no-deprecated rule.',
-      migrationScript: './scripts/003-update-eslint-deprecation-rule.js',
-    },
-    '004-eslint9-flat-config': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Migrate eslint config to flat config format and update devDependencies to latest versions.',
-      migrationScript: './scripts/004-eslint9-flat-config.js',
-    },
-    '005-react-18-3': {
-      version: '6.1.9',
-      description: 'Update React and ReactDOM 18.x versions to ^18.3.0 to surface React 19 compatibility issues.',
-      migrationScript: './scripts/005-react-18-3.js',
-    },
-    '006-webpack-nested-fix': {
-      version: '6.1.11',
-      description: 'Fix webpack variable replacement in nested plugins files.',
-      migrationScript: './scripts/006-webpack-nested-fix.js',
-    },
-    '007-remove-testing-library-types': {
-      version: '6.1.13',
-      description:
-        'Add setupTests.d.ts for @testing-library/jest-dom types and remove @types/testing-library__jest-dom npm package.',
-      migrationScript: './scripts/007-remove-testing-library-types.js',
-    },
-  },
-} as Migrations;

package/src/migrations/scripts/example-migration.test.ts

@@ -1,40 +0,0 @@
-import migrate from './example-migration.js';
-import { createDefaultContext } from '../test-utils.js';
-
-describe('Migration - append profile to webpack', () => {
-  test('should update the package.json', async () => {
-    const context = createDefaultContext();
-
-    context.updateFile(
-      './package.json',
-      JSON.stringify({
-        scripts: {
-          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
-        },
-      })
-    );
-
-    const updatedContext = await migrate(context);
-
-    expect(updatedContext.getFile('./package.json')).toMatch(
-      'webpack -c ./.config/webpack/webpack.config.ts --profile --env production'
-    );
-
-    expect(updatedContext.readDir('./src')).toEqual(['src/FOO.md', 'src/foo.json']);
-  });
-
-  it('should not make additional changes when run multiple times', async () => {
-    const context = await createDefaultContext();
-
-    await context.updateFile(
-      './package.json',
-      JSON.stringify({
-        scripts: {
-          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
-        },
-      })
-    );
-
-    await expect(migrate).toBeIdempotent(context);
-  });
-});

package/src/migrations/scripts/example-migration.ts

@@ -1,34 +0,0 @@
-import type { Context } from '../context.js';
-
-export default function migrate(context: Context): Context {
-  const rawPkgJson = context.getFile('./package.json') ?? '{}';
-  const packageJson = JSON.parse(rawPkgJson);
-
-  if (packageJson.scripts && packageJson.scripts.build) {
-    const buildScript = packageJson.scripts.build;
-
-    const pattern = /(webpack.+-c\s.+\.ts)\s(.+)/;
-
-    if (pattern.test(buildScript) && !buildScript.includes('--profile')) {
-      packageJson.scripts.build = buildScript.replace(pattern, `$1 --profile $2`);
-    }
-
-    context.updateFile('./package.json', JSON.stringify(packageJson, null, 2));
-  }
-
-  if (context.doesFileExist('./src/README.md')) {
-    context.deleteFile('./src/README.md');
-  }
-
-  if (!context.doesFileExist('./src/foo.json')) {
-    context.addFile('./src/foo.json', JSON.stringify({ foo: 'bar' }));
-  }
-
-  if (context.doesFileExist('.eslintrc')) {
-    context.renameFile('.eslintrc', '.eslint.config.json');
-  }
-
-  context.readDir('./src');
-
-  return context;
-}