@grafana/create-plugin 6.3.1 → 6.4.0-canary.2314.19664595751.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.4.0-canary.2314.19664595751.0",
|
|
4
4
|
"repository": {
|
|
5
5
|
"directory": "packages/create-plugin",
|
|
6
6
|
"url": "https://github.com/grafana/plugin-tools"
|
|
@@ -56,5 +56,5 @@
|
|
|
56
56
|
"engines": {
|
|
57
57
|
"node": ">=20"
|
|
58
58
|
},
|
|
59
|
-
"gitHead": "
|
|
59
|
+
"gitHead": "1584dab6b5559b64734428041dd52e98071289eb"
|
|
60
60
|
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: panel-plugin-agent-fundamentals
|
|
3
|
+
description: Develops Grafana panel plugins
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
You are an expert Grafana panel plugin developer for this project.
|
|
7
|
+
|
|
8
|
+
## Your role
|
|
9
|
+
|
|
10
|
+
- You are fluent in TypeScript and React
|
|
11
|
+
- You know how to use Grafana dashboards
|
|
12
|
+
|
|
13
|
+
## Project knowledge
|
|
14
|
+
|
|
15
|
+
This repository contains a **Grafana panel plugin**, providing a custom visualization for Grafana dashboards.
|
|
16
|
+
Panel plugins are used to:
|
|
17
|
+
|
|
18
|
+
- Display data from Grafana data sources in custom ways
|
|
19
|
+
- Add interactive behavior (drill-downs, navigation, etc.)
|
|
20
|
+
- Visualize or control external systems (IoT, integrations, custom controls)
|
|
21
|
+
|
|
22
|
+
### Plugin anatomy
|
|
23
|
+
|
|
24
|
+
A typical panel plugin includes:
|
|
25
|
+
|
|
26
|
+
**plugin.json**
|
|
27
|
+
|
|
28
|
+
- Declares plugin ID, type (`panel`), name, version
|
|
29
|
+
- Loaded by Grafana at startup
|
|
30
|
+
|
|
31
|
+
**Main module (`src/module.ts`)**
|
|
32
|
+
|
|
33
|
+
- Exports: `new PanelPlugin(PanelComponent)`
|
|
34
|
+
- Registers panel options, migrations, defaults, ui extensions
|
|
35
|
+
|
|
36
|
+
**Panel component (`src/components/Panel.tsx`)**
|
|
37
|
+
|
|
38
|
+
- React component receiving: `data`, `timeRange`, `width`, `height`, `options`
|
|
39
|
+
- Renders visualization using Grafana data frames and field configs
|
|
40
|
+
|
|
41
|
+
### Repository layout
|
|
42
|
+
|
|
43
|
+
- `plugin.json` — Panel plugin manifest
|
|
44
|
+
- `src/module.ts` — Main plugin entry
|
|
45
|
+
- `src/components/` — Panel React components
|
|
46
|
+
- `src/types.ts` — Option and model types
|
|
47
|
+
- `tests/` — E2E tests (if present)
|
|
48
|
+
- `provisioning/` — Local development provisioning
|
|
49
|
+
- `README.md` — Human documentation
|
|
50
|
+
|
|
51
|
+
## Coding guidelines
|
|
52
|
+
|
|
53
|
+
- Use **TypeScript** (in strict mode), functional React components, and idiomatic patterns
|
|
54
|
+
- Use **@grafana/ui**, **@grafana/data**, **@grafana/runtime**
|
|
55
|
+
- Use **`useTheme2()`** for all colors, spacing, typography
|
|
56
|
+
- **Never hardcode** colors, spacing, padding, or font sizes
|
|
57
|
+
- Use **Emotion** + `useStyles2()` + theme tokens for styling
|
|
58
|
+
- Keep layouts responsive (use `width`/`height`)
|
|
59
|
+
- Avoid new dependencies unless necessary + Grafana-compatible
|
|
60
|
+
- Maintain consistent file structure and predictable types
|
|
61
|
+
- Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI.
|
|
62
|
+
|
|
63
|
+
## Boundaries
|
|
64
|
+
|
|
65
|
+
You must **NOT**:
|
|
66
|
+
|
|
67
|
+
- Change plugin ID or plugin type in `plugin.json`
|
|
68
|
+
- Modify anything inside `.config/*`
|
|
69
|
+
- Add a backend (panel plugins = frontend only)
|
|
70
|
+
- Remove/change existing options without a migration handler
|
|
71
|
+
- Break public APIs (options, field configs, panel props)
|
|
72
|
+
- Store, read, or handle credentials
|
|
73
|
+
|
|
74
|
+
You **SHOULD**:
|
|
75
|
+
|
|
76
|
+
- Maintain backward compatibility
|
|
77
|
+
- Preserve option schema unless migration handler is added
|
|
78
|
+
- Follow official Grafana panel plugin patterns
|
|
79
|
+
- Use idiomatic React + TypeScript
|
|
80
|
+
|
|
81
|
+
## Instructions for specific tasks
|
|
82
|
+
|
|
83
|
+
- [Add panel options](./tasks/add-panel-options.md)
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Adding a New Panel Option
|
|
2
|
+
|
|
3
|
+
Panel options are settings the user configures to change panel behavior.
|
|
4
|
+
|
|
5
|
+
Always complete **all three steps**:
|
|
6
|
+
|
|
7
|
+
### **1. Extend the options type**
|
|
8
|
+
|
|
9
|
+
File: `src/types.ts`
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
export interface SimpleOptions {
|
|
13
|
+
// existing...
|
|
14
|
+
myOptionName: MyOptionType;
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- Property name must match the builder `path`.
|
|
19
|
+
- Type must match expected editor output.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
### **2. Register the option in `setPanelOptions`**
|
|
24
|
+
|
|
25
|
+
File: `src/module.ts` inside `setPanelOptions((builder) => { ... })`
|
|
26
|
+
|
|
27
|
+
Use the correct builder method:
|
|
28
|
+
|
|
29
|
+
| Type | Builder |
|
|
30
|
+
| ------------------ | -------------------- |
|
|
31
|
+
| boolean | `addBooleanSwitch` |
|
|
32
|
+
| number | `addNumberInput` |
|
|
33
|
+
| string | `addTextInput` |
|
|
34
|
+
| select | `addSelect` |
|
|
35
|
+
| radio | `addRadio` |
|
|
36
|
+
| radio group | `addRadio` |
|
|
37
|
+
| slider | `addSliderInput` |
|
|
38
|
+
| color picker | `addColorPicker` |
|
|
39
|
+
| unit picker | `addUnitPicker` |
|
|
40
|
+
| field namer picker | `addFieldNamePicker` |
|
|
41
|
+
|
|
42
|
+
Template:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
builder.addXxx({
|
|
46
|
+
path: 'myOptionName', // must match type property
|
|
47
|
+
name: 'My option',
|
|
48
|
+
defaultValue: <default>,
|
|
49
|
+
description: '',
|
|
50
|
+
settings: { /* optional */ },
|
|
51
|
+
// Optional visibility rule:
|
|
52
|
+
// showIf: (opts) => opts.someOtherOption,
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Rules:
|
|
57
|
+
|
|
58
|
+
- Every option **must** have a `defaultValue`.
|
|
59
|
+
- Put numeric constraints in `settings` (`min`, `max`, `step`).
|
|
60
|
+
- Use `showIf` for conditional display.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
### **3. Use the option in the panel component**
|
|
65
|
+
|
|
66
|
+
File: `src/Panel.tsx` (or equivalent)
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
export const Panel = ({ options }) => {
|
|
70
|
+
const { myOptionName } = options;
|
|
71
|
+
// apply it in rendering/logic
|
|
72
|
+
};
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
No option may remain unused.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
# Quick Editor Recipes
|
|
80
|
+
|
|
81
|
+
### **Boolean**
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
.addBooleanSwitch({ path: 'flag', name: 'Flag', defaultValue: false })
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### **Number**
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
.addNumberInput({
|
|
91
|
+
path: 'max',
|
|
92
|
+
name: 'Max value',
|
|
93
|
+
defaultValue: 10,
|
|
94
|
+
settings: { min: 1, max: 100, step: 1 },
|
|
95
|
+
})
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### **String**
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
.addTextInput({ path: 'label', name: 'Label', defaultValue: '' })
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### **Select**
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
.addSelect({
|
|
108
|
+
path: 'mode',
|
|
109
|
+
name: 'Mode',
|
|
110
|
+
defaultValue: 'auto',
|
|
111
|
+
settings: { options: [
|
|
112
|
+
{ value: 'a', label: 'A' },
|
|
113
|
+
{ value: 'b', label: 'B' },
|
|
114
|
+
]},
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### **Radio**
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
.addRadio({
|
|
122
|
+
path: 'size',
|
|
123
|
+
name: 'Size',
|
|
124
|
+
defaultValue: 'md',
|
|
125
|
+
settings: { options: [
|
|
126
|
+
{ value: 'sm', label: 'Small' },
|
|
127
|
+
{ value: 'md', label: 'Medium' },
|
|
128
|
+
{ value: 'lg', label: 'Large' },
|
|
129
|
+
]},
|
|
130
|
+
showIf: (o) => o.showSize,
|
|
131
|
+
})
|
|
132
|
+
```
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: panel-plugin-agent
|
|
3
|
+
description: Develops Grafana panel plugins
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Project knowledge
|
|
7
|
+
|
|
8
|
+
This repository contains a **Grafana panel plugin**. Follow the [instructions](./.config/AGENTS/instructions.md) before doing any changes.
|
|
9
|
+
|
|
10
|
+
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.
|