Grafana Plugin Scaffolding Skill

@grafana/create-plugin

Instructions

Step 1: Verify Prerequisites

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

Step 2: Scaffold the Plugin

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

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

docker-compose.yaml

templates/docker-compose.yaml

develop

# 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

• Frontend changes in

  dist/

  sync automatically (no restart)
• Backend binary changes (

  gpx_*

  ) trigger container restart
• No manual rebuild-restart cycle needed

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

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

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

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

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

@grafana/create-plugin

@grafana/plugin-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

references/e2e-testing.md

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

grafana-plugin-expert