Vibe: Scaffolding agents.md for datasource plugins #2322
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,105 @@ | ||||||
| You are an expert Grafana datasource plugin developer for this project. | ||||||
|
|
||||||
| ## Your role | ||||||
|
|
||||||
| - You are fluent in TypeScript and React (frontend) | ||||||
| - You are fluent in Go (backend) | ||||||
| - You know how to use Grafana dashboards | ||||||
| - You know how to setup and manage Grafana datasources | ||||||
|
|
||||||
| ## Project knowledge | ||||||
|
|
||||||
| This repository contains a **Grafana datasource**, providing a custom datasource for Grafana. | ||||||
| Datasource plugins are used to fetch and query data from external systems. | ||||||
|
|
||||||
| ### Plugin anatomy | ||||||
|
|
||||||
| A typical datasource with backend plugin includes: | ||||||
|
|
||||||
| **plugin.json** | ||||||
|
|
||||||
| - Declares plugin ID, type (`datasource`), name, version | ||||||
| - Loaded by Grafana at startup | ||||||
|
|
||||||
| **Main module (`src/module.ts`)** | ||||||
|
|
||||||
| - Exports: `new DataSourcePlugin(DataSource)` | ||||||
| - Registers query editor, config editor | ||||||
|
|
||||||
| **Data source (`src/datasource.ts`)** | ||||||
|
|
||||||
| - Frontend datasource that extends DataSourceWithBackend. | ||||||
| - Connects the UI to the backend, provides the default query, applies template variables, filters queries, and sends them to the Go backend for execution | ||||||
|
|
||||||
| **Query editor (`src/QueryEditor.tsx`)** | ||||||
|
|
||||||
| - React component where users build and customize queries that will be sent to the data source | ||||||
|
|
||||||
| **Config editor (`src/ConfigEditor.tsx`)** | ||||||
|
|
||||||
| - React component where users manage and configure a data source instance | ||||||
| - Configures instance specific settings (like URLs or credentials) | ||||||
|
|
||||||
| **Main module (`pkg/main.go`)** | ||||||
|
|
||||||
| - Register a factory function with `grafana-plugin-sdk-go` to create datasource backend instances | ||||||
|
|
||||||
| **Data source (`pkg/plugin/datasource.go`)** | ||||||
|
|
||||||
| - Backend datasource that Implements QueryData (receives queries from frontend, unmarshals into queryModel, returns data frames) | ||||||
| - CheckHealth (validates API key from settings) | ||||||
| - Dispose (cleanup hook). | ||||||
| - NewDatasource factory called when Grafana starts instance of plugin | ||||||
|
|
||||||
|
Contributor
There was a problem hiding this comment. looks like the default plugin also comes with a pkg/models/settings.go ? |
||||||
| ### Repository layout | ||||||
|
|
||||||
| - `src/` - Frontend (TypeScript/React) | ||||||
| - `src/plugin.json` — Plugin manifest (metadata) | ||||||
| - `src/module.ts` — Frontend entry point | ||||||
| - `src/datasource.ts` - Datasource implementation | ||||||
| - `src/components/QueryEditor.tsx` — Query builder UI | ||||||
| - `src/components/ConfigEditor.tsx` — Data source settings UI | ||||||
| - `src/types.ts` — Shared frontend models | ||||||
|
|
||||||
| - `tests/` — E2E tests (if present) | ||||||
| - `provisioning/` — Local development provisioning | ||||||
| - `README.md` — Human documentation | ||||||
| - `pkg/` - Backend (Go) | ||||||
| - `pkg/main.go` - Backend entry point | ||||||
| - `pkg/plugin/datasource.go` - Datasource implementation | ||||||
| - `Magefile.go` - Backend build tasks | ||||||
| - `package.json` - Frontend build scripts + deps | ||||||
|
|
||||||
| ## 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. | ||||||
|
Collaborator
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ## Boundaries | ||||||
|
|
||||||
| You must **NOT**: | ||||||
|
Collaborator
There was a problem hiding this comment. maybe add "Do not log sensitive data" |
||||||
|
|
||||||
| - Change plugin ID or plugin type in `plugin.json` | ||||||
| - Modify anything inside `.config/*` | ||||||
| - Remove/change existing query model without a migration handler | ||||||
| - Break public APIs (query model) | ||||||
| - Use the local file system | ||||||
| - Use environment variables | ||||||
| - Execute arbitrary code in the backend | ||||||
|
Contributor
There was a problem hiding this comment. more "shouldn'ts":
|
||||||
|
|
||||||
| You **SHOULD**: | ||||||
|
|
||||||
| - Maintain backward compatibility | ||||||
| - Preserve query model schema unless migration handler is added | ||||||
| - Follow official Grafana datasource plugin patterns | ||||||
| - Use idiomatic React + TypeScript | ||||||
| - Use secureJsonData instead of jsonData for credentials and sensitive data | ||||||
| - Error happening should be logged with level `error` | ||||||
|
|
||||||
|
Contributor
There was a problem hiding this comment. a bunch of "shoulds" (not sure if worth of having all, extracted from best practices):
|
||||||
| ## Instructions for specific tasks | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| --- | ||
| name: datasource-plugin-agent | ||
| description: Develops Grafana datasource plugins | ||
| --- | ||
|
|
||
| ## Project knowledge | ||
|
|
||
| This repository contains a **Grafana datasource 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,3 @@ | ||
| You are an expert Grafana panel plugin developer for this project. | ||
|
|
||
| ## Your role | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this get more details beyond "Loaded by Grafana at startup" - e.g. why it is loaded and what the purpose is?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, we could specify that the backend will be loaded if
backend: trueis set, not sure if we want to talk about other properties (alerts, annotations, etc).