@grafana/create-plugin 6.2.0 → 6.3.0-canary.2314.19529525779.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grafana/create-plugin",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.3.0-canary.2314.19529525779.0",
|
|
4
4
|
"repository": {
|
|
5
5
|
"directory": "packages/create-plugin",
|
|
6
6
|
"url": "https://github.com/grafana/plugin-tools"
|
|
@@ -61,5 +61,5 @@
|
|
|
61
61
|
"engines": {
|
|
62
62
|
"node": ">=20"
|
|
63
63
|
},
|
|
64
|
-
"gitHead": "
|
|
64
|
+
"gitHead": "41ae4942f75e34ef8c07414e6a9eb07c8c3cb058"
|
|
65
65
|
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Project overview
|
|
2
|
+
|
|
3
|
+
This repository contains a **Grafana panel plugin**, providing a custom visualization for Grafana dashboards.
|
|
4
|
+
Panel plugins are used to:
|
|
5
|
+
|
|
6
|
+
- Display data from Grafana data sources in custom ways
|
|
7
|
+
- Add interactive behavior (drill-downs, navigation, etc.)
|
|
8
|
+
- Visualize or control external systems (IoT, integrations, custom controls)
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Plugin anatomy
|
|
13
|
+
|
|
14
|
+
A typical panel plugin includes:
|
|
15
|
+
|
|
16
|
+
## **plugin.json**
|
|
17
|
+
|
|
18
|
+
- Declares plugin ID, type (`panel`), name, version
|
|
19
|
+
- Loaded by Grafana at startup
|
|
20
|
+
|
|
21
|
+
## **Main module (`src/module.ts`)**
|
|
22
|
+
|
|
23
|
+
- Exports: `new PanelPlugin(PanelComponent)`
|
|
24
|
+
- Registers panel options, migrations, defaults, ui extensions
|
|
25
|
+
|
|
26
|
+
## **Panel component (`src/components/Panel.tsx`)**
|
|
27
|
+
|
|
28
|
+
- React component receiving: `data`, `timeRange`, `width`, `height`, `options`
|
|
29
|
+
- Renders visualization using Grafana data frames and field configs
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
# Agent goals
|
|
34
|
+
|
|
35
|
+
Agents must:
|
|
36
|
+
|
|
37
|
+
- Preserve the existing options schema unless adding a migration handler
|
|
38
|
+
- Follow idiomatic React + TypeScript patterns used in official Grafana examples
|
|
39
|
+
- Treat **`AGENTS.md` as the authoritative source** over `.config/AGENTS/*`
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
# Repository layout
|
|
44
|
+
|
|
45
|
+
- `plugin.json` — Panel plugin manifest
|
|
46
|
+
- `src/module.ts` — Main plugin entry
|
|
47
|
+
- `src/components/` — Panel React components
|
|
48
|
+
- `src/types.ts` — Option and model types
|
|
49
|
+
- `tests/` — E2E tests (if present)
|
|
50
|
+
- `provisioning/` — Local development provisioning
|
|
51
|
+
- `README.md` — Human documentation
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
# Coding guidelines
|
|
56
|
+
|
|
57
|
+
- Use **TypeScript** and **functional React components**
|
|
58
|
+
- Use **@grafana/ui**, **@grafana/data**, **@grafana/runtime**
|
|
59
|
+
- Respect `width` and `height`; keep layout responsive
|
|
60
|
+
- Avoid unnecessary dependencies; ensure Grafana compatibility
|
|
61
|
+
- Use useTheme2() from @grafana/ui for visual tokens
|
|
62
|
+
- Avoid to hardcode colors, spacing, padding, or font sizes
|
|
63
|
+
- Follow existing file structure
|
|
64
|
+
- Keep code typed and predictable
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
# Safety & constraints
|
|
69
|
+
|
|
70
|
+
Agents must **not**:
|
|
71
|
+
|
|
72
|
+
- Change plugin IDs or plugin type in `plugin.json`
|
|
73
|
+
- Modify anything under `.config/*`
|
|
74
|
+
- Add a backend — panel plugins are **frontend only**
|
|
75
|
+
- Remove or change existing options without a migration handler
|
|
76
|
+
- Break public APIs (options, field configs, panel props)
|
|
77
|
+
- Store or use credentials.
|
|
78
|
+
|
|
79
|
+
Agents **should**:
|
|
80
|
+
|
|
81
|
+
- Keep the plugin backward compatible
|
|
82
|
+
- Mirror patterns from Grafana’s official panel plugin examples
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
# How-to
|
|
87
|
+
|
|
88
|
+
- [How-to add panel options](./howto/add-panel-options.md)
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Adding a New Panel Option
|
|
2
|
+
|
|
3
|
+
Always complete **all three steps**:
|
|
4
|
+
|
|
5
|
+
### **1. Extend the options type**
|
|
6
|
+
|
|
7
|
+
File: `src/types.ts`
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
export interface SimpleOptions {
|
|
11
|
+
// existing...
|
|
12
|
+
myOptionName: MyOptionType;
|
|
13
|
+
}
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
* Property name must match the builder `path`.
|
|
17
|
+
* Type must match expected editor output.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
### **2. Register the option in `setPanelOptions`**
|
|
22
|
+
|
|
23
|
+
File: `src/module.ts` inside `setPanelOptions((builder) => { ... })`
|
|
24
|
+
|
|
25
|
+
Use the correct builder method:
|
|
26
|
+
|
|
27
|
+
| Type | Builder |
|
|
28
|
+
| ------------------ | -------------------- |
|
|
29
|
+
| boolean | `addBooleanSwitch` |
|
|
30
|
+
| number | `addNumberInput` |
|
|
31
|
+
| string | `addTextInput` |
|
|
32
|
+
| select | `addSelect` |
|
|
33
|
+
| radio | `addRadio` |
|
|
34
|
+
| radio group | `addRadio` |
|
|
35
|
+
| slider | `addSliderInput` |
|
|
36
|
+
| color picker | `addColorPicker` |
|
|
37
|
+
| unit picker | `addUnitPicker` |
|
|
38
|
+
| field namer picker | `addFieldNamePicker` |
|
|
39
|
+
|
|
40
|
+
Template:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
builder.addXxx({
|
|
44
|
+
path: 'myOptionName', // must match type property
|
|
45
|
+
name: 'My option',
|
|
46
|
+
defaultValue: <default>,
|
|
47
|
+
description: '',
|
|
48
|
+
settings: { /* optional */ },
|
|
49
|
+
// Optional visibility rule:
|
|
50
|
+
// showIf: (opts) => opts.someOtherOption,
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Rules:
|
|
55
|
+
|
|
56
|
+
* Every option **must** have a `defaultValue`.
|
|
57
|
+
* Put numeric constraints in `settings` (`min`, `max`, `step`).
|
|
58
|
+
* Use `showIf` for conditional display.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
### **3. Use the option in the panel component**
|
|
63
|
+
|
|
64
|
+
File: `src/Panel.tsx` (or equivalent)
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
export const Panel = ({ options }) => {
|
|
68
|
+
const { myOptionName } = options;
|
|
69
|
+
// apply it in rendering/logic
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
No option may remain unused.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
# Quick Editor Recipes
|
|
78
|
+
|
|
79
|
+
### **Boolean**
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
.addBooleanSwitch({ path: 'flag', name: 'Flag', defaultValue: false })
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### **Number**
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
.addNumberInput({
|
|
89
|
+
path: 'max',
|
|
90
|
+
name: 'Max value',
|
|
91
|
+
defaultValue: 10,
|
|
92
|
+
settings: { min: 1, max: 100, step: 1 },
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### **String**
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
.addTextInput({ path: 'label', name: 'Label', defaultValue: '' })
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### **Select**
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
.addSelect({
|
|
106
|
+
path: 'mode',
|
|
107
|
+
name: 'Mode',
|
|
108
|
+
defaultValue: 'auto',
|
|
109
|
+
settings: { options: [
|
|
110
|
+
{ value: 'a', label: 'A' },
|
|
111
|
+
{ value: 'b', label: 'B' },
|
|
112
|
+
]},
|
|
113
|
+
})
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### **Radio**
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
.addRadio({
|
|
120
|
+
path: 'size',
|
|
121
|
+
name: 'Size',
|
|
122
|
+
defaultValue: 'md',
|
|
123
|
+
settings: { options: [
|
|
124
|
+
{ value: 'sm', label: 'Small' },
|
|
125
|
+
{ value: 'md', label: 'Medium' },
|
|
126
|
+
{ value: 'lg', label: 'Large' },
|
|
127
|
+
]},
|
|
128
|
+
showIf: (o) => o.showSize,
|
|
129
|
+
})
|
|
130
|
+
```
|