Vibe: Scaffolding agents.md for datasource plugins #2322
Conversation
github-project-automation
bot
moved this to 📬 Triage
in Plugins Platform / Grafana Community
mckn
moved this from 📬 Triage
to 🧑💻 In development
in Plugins Platform / Grafana Community
|
Hello! 👋 This repository uses Auto for releasing packages using PR labels. ✨ This PR can be merged but will not trigger a new release. To trigger a new release add the |
mckn
added
create-plugin
| - `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 |
| - 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. |
There was a problem hiding this comment.
| - Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI. | |
| - Use npm package called **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI. |
| **plugin.json** | ||
|
|
||
| - Declares plugin ID, type (`datasource`), name, version | ||
| - Loaded by Grafana at startup |
There was a problem hiding this comment.
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.
yeah, we could specify that the backend will be loaded if backend: true is set, not sure if we want to talk about other properties (alerts, annotations, etc).
|
|
||
| ## Boundaries | ||
|
|
||
| You must **NOT**: |
There was a problem hiding this comment.
maybe add "Do not log sensitive data"
|
We should probably add CLAUDE.md file pointing to Agents.md like this: https://github.com/grafana/plugin-tools/blob/3aed54e7d9d26d14dfbaa229806c3377391ccfcc/CLAUDE.md?plain=1 |
andresmgot
left a comment
andresmgot
left a comment
There was a problem hiding this comment.
A bunch of comments here 👍
| **plugin.json** | ||
|
|
||
| - Declares plugin ID, type (`datasource`), name, version | ||
| - Loaded by Grafana at startup |
There was a problem hiding this comment.
yeah, we could specify that the backend will be loaded if backend: true is set, not sure if we want to talk about other properties (alerts, annotations, etc).
| - CheckHealth (validates API key from settings) | ||
| - Dispose (cleanup hook). | ||
| - NewDatasource factory called when Grafana starts instance of plugin | ||
|
|
There was a problem hiding this comment.
looks like the default plugin also comes with a pkg/models/settings.go ?
| - Use idiomatic React + TypeScript | ||
| - Use secureJsonData instead of jsonData for credentials and sensitive data | ||
| - Error happening should be logged with level `error` | ||
|
|
There was a problem hiding this comment.
a bunch of "shoulds" (not sure if worth of having all, extracted from best practices):
- Implement a health check
- Add template variables support
- Skip execution for hidden or empty queries
- Specify a default query
- Add support for alerting (if backend enabled)
- Keep cached connections (if backend enabled)
| - Break public APIs (query model) | ||
| - Use the local file system | ||
| - Use environment variables | ||
| - Execute arbitrary code in the backend |
There was a problem hiding this comment.
more "shouldn'ts":
- Use upstream Golang HTTP client, SHOULD use Grafana plugin SDK HTTP client instead.
- Use "info" log level, use "debug" or "error" instead.
|
|
||
| export const plugin = new DataSourcePlugin<DataSource, MyQuery, MyDataSourceOptions>(DataSource) | ||
| .setQueryEditor(QueryEditor) | ||
| .setVariableQueryEditor(VariableQueryEditor); |
There was a problem hiding this comment.
This approach is deprecated, better to use a more modern example
3 participants
What this PR does / why we need it:
It will add an agents.md file that cover the fundamentals of datasource plugins (with and without backend). We are following the convention where we put generic information below
.configfolder (which should not be modified by the developer). Then we reference that file from the projectAGENTS.mdwhere the developers of the plugin can add more plugin specific details.Which issue(s) this PR fixes:
Fixes https://github.com/grafana/grafana-community-team/issues/674
Special notes for your reviewer: