grafana-plugin-scaffolding

Grafana プラグインのスキャフォールディングスキル

公式の @grafana/create-plugin スキャフォールダーを使用して、Grafana プラグインプロジェクトの作成を自動化します。このスキルでは、すべてのプラグインタイプについて、プロジェクトのスキャフォールディング、開発環境のセットアップ、初期設定を行います。

対応する Grafana バージョン： v12.x+ のみ

手順

ステップ 1：前提条件を確認する

スキャフォールディングを始める前に、次のツールがインストールされていることを確認します。

# Check Node.js (v18+ required)
node --version

# Check npm
npm --version

# Check Docker (optional, for local development)
docker --version

前提条件を満たしていない場合は、次のリンクからインストールするようユーザーに案内します。

• Node.js：https://nodejs.org/
• Docker Desktop：https://www.docker.com/products/docker-desktop/

ステップ 2：プラグインをスキャフォールディングする

公式の @grafana/create-plugin ツールを使用します。

# Interactive scaffolding (recommended)
npx @grafana/create-plugin@latest

# The tool will prompt for:
# - Plugin type (panel, datasource, app, scenesapp)
# - Organization name (e.g., "myorg")
# - Plugin name (e.g., "my-panel")
# - Include backend? (y/n)

ステップ 3：移動して依存関係をインストールする

# Navigate to the new plugin directory
cd <orgName>-<pluginName>-<pluginType>

# Install frontend dependencies
npm install

# Install backend dependencies (if backend plugin)
go mod tidy

ステップ 4：開発環境を起動する

オプション A：ホットリロード対応の Docker（推奨）

スキャフォールダーは docker-compose.yaml を生成します。ファイル監視に対応したより快適な開発環境を利用するには、Docker Compose の develop 機能を含む templates/docker-compose.yaml のテンプレートを使用します。

# Start Grafana with file watching (Docker Compose v2.22.0+)
docker compose watch

# Or standard start without watching
docker compose up -d

# Access Grafana at http://localhost:3000
# Login: admin / admin

docker compose watch を使用すると、次のようになります。

• dist/ 内のフロントエンドの変更は自動的に同期されます（再起動不要）
• バックエンドバイナリの変更（gpx_*）によってコンテナが再起動します
• 手動での再ビルドと再起動を繰り返す必要はありません

オプション B：手動

# Build and watch frontend
npm run dev

# Build backend (if applicable)
mage -v

# Configure Grafana to load unsigned plugins
# Add to grafana.ini: plugins.allow_loading_unsigned_plugins = <plugin-id>

ステップ 5：プラグインのインストールを確認する

1. http://localhost:3000 を開きます
2. Administration > Plugins に移動します
3. プラグイン名を検索します
4. プラグインが表示され、ダッシュボードに追加できることを確認します

プラグインタイプ別のワークフロー

パネルプラグイン

npx @grafana/create-plugin@latest
# Select: panel
# Enter: organization name
# Enter: plugin name
# Backend: No (panels don't need backend)

スキャフォールディング後：

1. src/components/SimplePanel.tsx を編集して、可視化ロジックを実装します
2. src/types.ts を編集して、パネルオプションのインターフェースを設定します
3. src/module.ts を編集して、オプションの設定を行います

データソースプラグイン（フロントエンドのみ）

npx @grafana/create-plugin@latest
# Select: datasource
# Enter: organization name
# Enter: plugin name
# Backend: No

スキャフォールディング後：

1. src/datasource.ts を編集して、クエリロジックを実装します
2. src/ConfigEditor.tsx を編集して、接続設定を行います
3. src/QueryEditor.tsx を編集して、クエリビルダーの UI を実装します

データソースプラグイン（バックエンドあり）

npx @grafana/create-plugin@latest
# Select: datasource
# Enter: organization name
# Enter: plugin name
# Backend: Yes

スキャフォールディング後：

1. pkg/plugin/datasource.go を編集して、Go のクエリロジックを実装します
2. QueryData メソッドと CheckHealth メソッドを実装します
3. バックエンドをビルドします：mage -v

アプリプラグイン

npx @grafana/create-plugin@latest
# Select: app
# Enter: organization name
# Enter: plugin name
# Backend: Optional

スキャフォールディング後：

1. src/pages/ を編集して、アプリのページを作成します
2. ナビゲーション用に plugin.json の includes を更新します
3. React コンポーネントとして新しいページを追加します

開発コマンド

# Frontend development (watch mode)
npm run dev

# Frontend production build
npm run build

# Backend build (Go plugins)
mage -v

# Run unit tests
npm test

# Run E2E tests (requires Grafana running)
npx playwright test

# Lint code
npm run lint

# Type check
npm run typecheck

E2E テスト

@grafana/create-plugin スキャフォールダーには、@grafana/plugin-e2e と Playwright を使用した E2E テストのセットアップが含まれています。

# Install Playwright browsers
npx playwright install --with-deps chromium

# Start Grafana
docker compose up -d

# Run E2E tests
npx playwright test

# Run with UI mode (debugging)
npx playwright test --ui

テストのパターン、フィクスチャ、CI/CD の設定について詳しくは、references/e2e-testing.md を参照してください。

ベストプラクティス

1. シンプルに始める：最小限の機能から始めて、段階的に改善します
2. Docker を使用する：チームメンバー間で一貫した環境を維持します
3. 早い段階からテストする：開発中は頻繁にテストを実行します
4. 型安全性：すべてのフロントエンドコードで TypeScript を活用します
5. SDK の更新：@grafana/data、@grafana/ui、@grafana/runtime のバージョンを揃えます

よくある問題

プラグインが表示されない

• plugin.json の id フィールドが正しいことを確認します
• Docker のボリュームが正しくマウントされていることを確認します
• npm run dev がエラーなく完了したことを確認します

バックエンドプラグインのエラー

• mage -v を実行して Go コードを再ビルドします
• dist/ 内に plugin_start_linux_* または gpx_* バイナリが存在することを確認します
• plugin.json に "backend": true が設定されていることを確認します

開発サーバーの問題

• ブラウザーのキャッシュをクリアします
• Docker を再起動します：docker compose down && docker compose up -d
• Grafana のログを確認します：docker compose logs grafana

委任

複雑なアーキテクチャ上の判断、プラグインの設計パターン、またはトラブルシューティングについては、Context7 経由で最新の SDK ドキュメントを参照できる grafana-plugin-expert エージェントに委任してください。