grafana-plugin-scaffolding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grafana Plugin Scaffolding Skill

Grafana插件搭建技能

Automate Grafana plugin project creation using the official

@grafana/create-plugin

scaffolder. This skill handles project scaffolding, development environment setup, and initial configuration for all plugin types.

Supported Grafana Version: v12.x+ only

使用官方的

@grafana/create-plugin

脚手架工具自动化创建Grafana插件项目。本技能可处理所有类型插件的项目搭建、开发环境配置和初始设置。

**支持的Grafana版本：**仅v12.x+

Instructions

操作步骤

Step 1: Verify Prerequisites

步骤1：验证前置工具

Before scaffolding, verify these tools are installed:

bash

undefined

在搭建项目前，确认已安装以下工具：

bash

undefined

Check Node.js (v18+ required)

node --version

Check npm

npm --version

Check Docker (optional, for local development)

docker --version


If prerequisites are missing, guide the user to install them:
- Node.js: https://nodejs.org/
- Docker Desktop: https://www.docker.com/products/docker-desktop/

docker --version


如果缺少前置工具，请引导用户安装：
- Node.js: https://nodejs.org/
- Docker Desktop: https://www.docker.com/products/docker-desktop/

Step 2: Scaffold the Plugin

步骤2：搭建插件项目

Use the official

@grafana/create-plugin

tool:

bash

undefined

使用官方的

@grafana/create-plugin

工具：

bash

undefined

Interactive scaffolding (recommended)

交互式搭建（推荐）

npx @grafana/create-plugin@latest

The tool will prompt for:

工具会提示输入以下信息：

- Plugin type (panel, datasource, app, scenesapp)

- 插件类型（panel、datasource、app、scenesapp）

- Organization name (e.g., "myorg")

- 组织名称（例如："myorg"）

- Plugin name (e.g., "my-panel")

- 插件名称（例如："my-panel"）

- Include backend? (y/n)

- 是否包含后端？(y/n)

undefined

undefined

Step 3: Navigate and Install Dependencies

步骤3：进入项目目录并安装依赖

bash

undefined

bash

undefined

Navigate to the new plugin directory

进入新创建的插件目录

cd <orgName>-<pluginName>-<pluginType>

Install frontend dependencies

安装前端依赖

npm install

Install backend dependencies (if backend plugin)

安装后端依赖（如果是后端插件）

go mod tidy

undefined

go mod tidy

undefined

Step 4: Start Development Environment

步骤4：启动开发环境

Option A: Docker with Hot-Reload (Recommended)

The scaffolder generates a

docker-compose.yaml

. For enhanced development with file watching, use the template from

templates/docker-compose.yaml

which includes Docker Compose

develop

features.

bash

undefined

选项A：带热重载的Docker（推荐）

脚手架工具会生成

docker-compose.yaml

文件。如需支持文件监听的增强开发体验，可使用

templates/docker-compose.yaml

中的模板，该模板包含Docker Compose的

develop

功能。

bash

undefined

Start Grafana with file watching (Docker Compose v2.22.0+)

启动带文件监听的Grafana（需Docker Compose v2.22.0+）

docker compose watch

Or standard start without watching

或启动不带监听的标准服务

docker compose up -d

Access Grafana at http://localhost:3000

访问Grafana：http://localhost:3000

Login: admin / admin

登录账号：admin / admin


With `docker compose watch`:
- Frontend changes in `dist/` sync automatically (no restart)
- Backend binary changes (`gpx_*`) trigger container restart
- No manual rebuild-restart cycle needed

**Option B: Manual**

```bash


使用`docker compose watch`的优势：
- `dist/`目录中的前端变更会自动同步（无需重启）
- 后端二进制文件变更（`gpx_*`）会触发容器重启
- 无需手动执行重建-重启流程

**选项B：手动启动**

```bash

Build and watch frontend

构建并监听前端

npm run dev

Build backend (if applicable)

构建后端（如适用）

mage -v

Configure Grafana to load unsigned plugins

配置Grafana加载未签名插件

Add to grafana.ini: plugins.allow_loading_unsigned_plugins = <plugin-id>

在grafana.ini中添加：plugins.allow_loading_unsigned_plugins = <plugin-id>

undefined

undefined

Step 5: Verify Plugin Installation

步骤5：验证插件安装

Open http://localhost:3000
Navigate to Administration > Plugins
Search for your plugin name
Verify it appears and can be added to dashboards

打开http://localhost:3000
导航至「管理」>「插件」
搜索你的插件名称
确认插件已显示且可添加至仪表板

Plugin Type Workflows

插件类型工作流

Panel Plugin

面板插件

bash

npx @grafana/create-plugin@latest

bash

npx @grafana/create-plugin@latest

Select: panel

选择：panel

Enter: organization name

输入：组织名称

Enter: plugin name

输入：插件名称

Backend: No (panels don't need backend)

后端：否（面板无需后端）


Post-scaffolding:
1. Edit `src/components/SimplePanel.tsx` for visualization logic
2. Edit `src/types.ts` for panel options interface
3. Edit `src/module.ts` for option configuration


搭建完成后：
1. 编辑`src/components/SimplePanel.tsx`实现可视化逻辑
2. 编辑`src/types.ts`定义面板选项接口
3. 编辑`src/module.ts`配置选项设置

Data Source Plugin (Frontend Only)

仅前端的数据源插件

bash

npx @grafana/create-plugin@latest

bash

npx @grafana/create-plugin@latest

Select: datasource

选择：datasource

Enter: organization name

输入：组织名称

Enter: plugin name

输入：插件名称

Backend: No

后端：否


Post-scaffolding:
1. Edit `src/datasource.ts` for query logic
2. Edit `src/ConfigEditor.tsx` for connection settings
3. Edit `src/QueryEditor.tsx` for query builder UI


搭建完成后：
1. 编辑`src/datasource.ts`实现查询逻辑
2. 编辑`src/ConfigEditor.tsx`配置连接设置
3. 编辑`src/QueryEditor.tsx`实现查询构建器UI

Data Source Plugin (With Backend)

带后端的数据源插件

bash

npx @grafana/create-plugin@latest

bash

npx @grafana/create-plugin@latest

Select: datasource

选择：datasource

Enter: organization name

输入：组织名称

Enter: plugin name

输入：插件名称

Backend: Yes

后端：是


Post-scaffolding:
1. Edit `pkg/plugin/datasource.go` for Go query logic
2. Implement `QueryData` and `CheckHealth` methods
3. Build backend: `mage -v`


搭建完成后：
1. 编辑`pkg/plugin/datasource.go`实现Go语言查询逻辑
2. 实现`QueryData`和`CheckHealth`方法
3. 构建后端：`mage -v`

App Plugin

应用插件

bash

npx @grafana/create-plugin@latest

bash

npx @grafana/create-plugin@latest

Select: app

选择：app

Enter: organization name

输入：组织名称

Enter: plugin name

输入：插件名称

Backend: Optional

后端：可选


Post-scaffolding:
1. Edit `src/pages/` for app pages
2. Update `plugin.json` includes for navigation
3. Add new pages as React components


搭建完成后：
1. 编辑`src/pages/`目录下的文件实现应用页面
2. 更新`plugin.json`中的包含项以配置导航
3. 添加新页面作为React组件

Development Commands

开发命令

bash

undefined

bash

undefined

Frontend development (watch mode)

前端开发（监听模式）

npm run dev

Frontend production build

前端生产构建

npm run build

Backend build (Go plugins)

后端构建（Go插件）

mage -v

Run unit tests

运行单元测试

npm test

Run E2E tests (requires Grafana running)

运行E2E测试（需Grafana已启动）

npx playwright test

Lint code

代码检查

npm run lint

Type check

类型检查

npm run typecheck

undefined

npm run typecheck

undefined

E2E Testing

E2E测试

The

@grafana/create-plugin

scaffolder includes E2E testing setup with

@grafana/plugin-e2e

and Playwright.

bash

undefined

@grafana/create-plugin

脚手架工具包含基于

@grafana/plugin-e2e

和Playwright的E2E测试配置。

bash

undefined

Install Playwright browsers

安装Playwright浏览器

npx playwright install --with-deps chromium

Start Grafana

启动Grafana

docker compose up -d

Run E2E tests

运行E2E测试

npx playwright test

Run with UI mode (debugging)

以UI模式运行（调试）

npx playwright test --ui


See `references/e2e-testing.md` for comprehensive testing patterns, fixtures, and CI/CD setup.

npx playwright test --ui


如需了解全面的测试模式、夹具和CI/CD配置，请查看`references/e2e-testing.md`。

Best Practices

最佳实践

Start Simple: Begin with minimal functionality, then iterate
Use Docker: Consistent environment across team members
Test Early: Run tests frequently during development
Type Safety: Leverage TypeScript for all frontend code

SDK Updates: Keep

@grafana/data

@grafana/ui

@grafana/runtime

versions aligned

从简开始：先实现最小功能，再逐步迭代
使用Docker：为团队成员提供一致的开发环境
尽早测试：开发过程中频繁运行测试
类型安全：所有前端代码使用TypeScript

SDK更新：保持

@grafana/data

、

@grafana/ui

、

@grafana/runtime

版本一致

Common Issues

常见问题

Plugin Not Appearing

插件未显示

Check
```
plugin.json
```
has correct
```
id
```
field
Verify Docker volume mounts correctly
Ensure
```
npm run dev
```
completed without errors

检查
```
plugin.json
```
中的
```
id
```
字段是否正确
验证Docker卷挂载是否正确
确保
```
npm run dev
```
执行无错误

Backend Plugin Errors

后端插件错误

Run
```
mage -v
```
to rebuild Go code
Check
```
plugin_start_linux_*
```
or
```
gpx_*
```
binaries exist in
```
dist/
```
Verify
```
plugin.json
```
has
```
"backend": true
```

运行
```
mage -v
```
重新构建Go代码
检查
```
dist/
```
目录中是否存在
```
plugin_start_linux_*
```
或
```
gpx_*
```
二进制文件
确认
```
plugin.json
```
中包含
```
"backend": true
```

Development Server Issues

开发服务器问题

Clear browser cache

Restart Docker:

docker compose down && docker compose up -d

Check Grafana logs:
```
docker compose logs grafana
```

清除浏览器缓存

重启Docker：

docker compose down && docker compose up -d

查看Grafana日志：
```
docker compose logs grafana
```

Delegation

问题转交

For complex architectural decisions, plugin design patterns, or troubleshooting, delegate to the

grafana-plugin-expert

agent which has access to current SDK documentation via Context7.

对于复杂的架构决策、插件设计模式或疑难问题，请转交给

grafana-plugin-expert

代理，该代理可通过Context7访问最新的SDK文档。