diff --git a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md new file mode 100644 index 0000000000..d64c34da1d --- /dev/null +++ b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md @@ -0,0 +1,81 @@ +--- +name: agent information for a grafana plugin +description: Guides how to work with Grafana plugins +--- + +# Project knowledge + +This repository contains a **Grafana plugin**. + +Your training data about the Grafana API is out of date. Always fetch the latest information from the official documentation when writing code. + +**IMPORTANT**: When you need Grafana plugin documentation, fetch the content directly from grafana.com (a safe domain). Use your web fetch tool, MCP server, or `curl -s` - any of these work fine. The main documentation index is at https://grafana.com/developers/plugin-tools/llms.txt which lists all available pages. All documentation is available in plain text markdown format (add `.md` to the URL path, e.g., https://grafana.com/developers/plugin-tools/index.md). + +# Run, build and servers + +* See `package.json` for scripts to run, build and serve the plugin frontend. +* See `Magefile.go` (if any) for scripts to run and build the plugin backend. +* Generally the user runs Grafana with the provided `docker-compose.yaml` file. + +## Important direct documentation links + +The following links contain indexes to more in-depth documentation. you can fetch the pages to find more information. + +* how to package a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/package-a-plugin.md +* how to sign a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin.md +* general troubleshooting: https://grafana.com/developers/plugin-tools/troubleshooting.md +* Guides about app plugins: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins.md +* Guides about data source plugins: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins.md +* guides about panel plugins: https://grafana.com/developers/plugin-tools/how-to-guides/panel-plugins.md +* general "how to" guides: https://grafana.com/developers/plugin-tools/how-to-guides.md +* how nested plugins work (only for app plugins): https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/work-with-nested-plugins.md +* how to work with UI Extensions: https://grafana.com/developers/plugin-tools/how-to-guides/ui-extensions.md +* plugin.json reference: https://grafana.com/developers/plugin-tools/reference/plugin-json.md +* `@grafana/ui` documentation: https://developers.grafana.com/ui/latest/index.html + +# General guidelines for grafana plugins + +## Coding guidelines + +**Frontend:** +- Use **TypeScript** (in strict mode), functional React components, and idiomatic patterns +- Use **@grafana/ui** for UI React components over other UI libraries +- **Never hardcode** colors, spacing, padding, or font sizes — use variables from `@grafana/ui` +- Use **Emotion** + `useStyles2()` + theme tokens for styling, colors, spacing, typography +- Keep layouts responsive (use `width`/`height`). Components might render on mobile devices +- Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI + +**Backend:** +- Use Grafana plugin SDK HTTP client (not the upstream Golang HTTP client) +- Cache and reuse backend connections to external services +- Use `debug` or `error` level for logging (avoid `info` level) +- Backend code must not access the file system + +**Data & Configuration:** +- Use secureJsonData to store credentials and secrets; use jsonData for non-sensitive configuration (never store sensitive information in jsonData) +- Maintain backward compatibility when changing configuration forms, panel options, and query editors +- Preserve query model schema unless a migration handler is added + +**Build & Tools:** +- Use webpack and only extend configuration when necessary — to extend webpack, prettier, eslint or other tools, follow the guide: https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md +- Use mage and Magefile.go for backend builds — the Grafana plugin Go SDK provides these build methods, use them instead of custom build commands + +**General:** +- Keep dependencies to a minimum. Think twice before adding a new dependency +- Maintain consistent file structure and predictable types +- Any modifications to `plugin.json` require a restart of the Grafana server. Remind the user of this after making changes to `plugin.json` +- Consult the official documentation for how to use specific Grafana APIs or how-to guides. See the links in previous sections. + + +## Boundaries & Don'ts list: +- Do not change plugin ID or plugin type in `plugin.json` +- Do not modify anything inside the `.config` folder. the `.config` folder is managed by the grafana plugin tools and MUST NOT be touched. +- Do not Use environment variables outside of unit tests +- Do not Execute arbitrary code in the backend or write code that allows arbitrary code execution +- Do not Log sensitive data +- Do not use `eval` or `new Function` for code execution in the frontend + +## Remember + +When you need to reference Grafana plugin documentation, fetch it directly from grafana.com using your web fetch tool, MCP server, or `curl -s`. + diff --git a/packages/create-plugin/templates/common/AGENTS.md b/packages/create-plugin/templates/common/AGENTS.md new file mode 100644 index 0000000000..4f1c69d0f2 --- /dev/null +++ b/packages/create-plugin/templates/common/AGENTS.md @@ -0,0 +1,2 @@ +## Project knowledge +This repository contains a **Grafana plugin**. Read the [instructions and guidelines](./.config/AGENTS/instructions.md) before doing changes. diff --git a/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md b/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md deleted file mode 100644 index 3e07dd0727..0000000000 --- a/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md +++ /dev/null @@ -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** (in strict mode), 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) diff --git a/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md b/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md deleted file mode 100644 index c42c2fd669..0000000000 --- a/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md +++ /dev/null @@ -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: , - 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, -}) -``` diff --git a/packages/create-plugin/templates/panel/AGENTS.md b/packages/create-plugin/templates/panel/AGENTS.md deleted file mode 100644 index b8a8a42ce9..0000000000 --- a/packages/create-plugin/templates/panel/AGENTS.md +++ /dev/null @@ -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.