Index of every page on this site: llms.txt
All skills
nodnarbnitram avatar

/grafana-plugin-scaffolding

@35e7f7d
Run it yourself

Scaffold and automate Grafana plugin projects using @grafana/create-plugin. Use when creating panel plugins, data source plugins, app plugins, or backend plugins. Handles project scaffolding, Docker dev environment setup, and plugin configuration.

Use this Skill: https://skilld.dev/gh/nodnarbnitram/claude-code-extensions/grafana-plugin-scaffolding

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈69 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈14k more on demand in 11 files.

Description uses 3.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈276 characters, or 3.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Grafana Plugin Scaffolding Skill

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

Instructions

Step 1: Verify Prerequisites

Before scaffolding, verify these tools are installed:

# 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:

Step 2: Scaffold the Plugin

Use the official @grafana/create-plugin tool:

# 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)

Step 3: Navigate and Install Dependencies

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

# Install frontend dependencies
npm install

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

Step 4: Start Development Environment

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.

# 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

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

# 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>

Step 5: Verify Plugin Installation

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

Plugin Type Workflows

Panel Plugin

npx @grafana/create-plugin@latest
# Select: 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

Data Source Plugin (Frontend Only)

npx @grafana/create-plugin@latest
# Select: 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

Data Source Plugin (With Backend)

npx @grafana/create-plugin@latest
# Select: 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

App Plugin

npx @grafana/create-plugin@latest
# Select: 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

Development Commands

# 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 Testing

The @grafana/create-plugin scaffolder includes E2E testing setup with @grafana/plugin-e2e and Playwright.

# 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

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

Best Practices

  1. Start Simple: Begin with minimal functionality, then iterate
  2. Use Docker: Consistent environment across team members
  3. Test Early: Run tests frequently during development
  4. Type Safety: Leverage TypeScript for all frontend code
  5. SDK Updates: Keep @grafana/data, @grafana/ui, @grafana/runtime versions aligned

Common Issues

Plugin Not Appearing

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

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

Development Server Issues

  • Clear browser cache
  • Restart Docker: docker compose down && docker compose up -d
  • Check Grafana logs: 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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo4 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides a legitimate and safe workflow for scaffolding Grafana plugins using official tools like @grafana/create-plugin. It includes templates and documentation for development, testing, and publishing while adhering to standard security practices.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    14/14 files flagged

Signed by skilld at 35e7f7d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 8 months ago
What it can do
Runs commands Reads files Edits files
All 6 allowed tools
BashReadWriteEditGrepGlob

README badge

README badge for nodnarbnitram/claude-code-extensions/grafana-plugin-scaffolding