# Grafana Jsonnet Refactor

> Refactors Grafana Jsonnet dashboards to eliminate duplication and align with available unified libraries while preserving behavior. Use when dashboards contain duplicated code, inconsistent patterns, legacy panel types, or need standardization with existing conventions. Produces single self-contained files without dashboard-specific libraries. Use when this capability is needed.

- Skill: `tomevault-io/grafana-jsonnet-refactor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/grafana-jsonnet-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/grafana-jsonnet-refactor/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/grafana-jsonnet-refactor

---


# Grafana Jsonnet Refactor

Eliminate duplication and align existing Jsonnet dashboards with available unified libraries. Preserve behavior while modernizing legacy panels and standardizing patterns.

**Not suitable for**: Initial JSON to Jsonnet conversion (use `grafana-json-to-jsonnet`), content optimization (use `grafana-dashboard-optimize`), or Python report migration (use `grafana-report-to-dashboard`).

## Workflow with progress tracking

Copy this checklist and track your progress:

```
Refactor Progress:
- [ ] Step 1: Read refactor-checklist.md and align with conventions
- [ ] Step 2: Audit dashboard (panels, variables, datasources, patterns)
- [ ] Step 3: Choose refactor mode (direct/wrapper/hybrid)
- [ ] Step 4: Normalize config and shared selectors
- [ ] Step 5: Replace panels with unified constructors
- [ ] Step 6: Organize file structure (imports → config → variables/helpers → panels → rows → dashboard)
- [ ] Step 7: Compile and verify in Grafana
```

**Step 1: Read refactor-checklist.md**

Load `references/refactor-checklist.md` to understand local conventions and standards.
If the dashboard belongs to a specific repo or stack, review the local Jsonnet defaults and docs in the working directory (datasource config, time range, variables, panel types).

**Step 2: Audit the dashboard**

List all panels, variables, datasources, and identify repeated patterns. Note which panels use local helpers vs unified libraries, and whether annotations or dashboard metadata (`__inputs`, `__requires`, `schemaVersion`, `graphTooltip`, `version`) are present.

**Step 3: Choose refactor mode**

Select approach based on dashboard size:
- **Direct migration**: Remove helpers, use unified libs directly (recommended for small dashboards)
- **Wrapper pattern**: Keep helper signatures, call unified libs internally (for large dashboards with many callsites)
- **Hybrid**: Mix approaches where needed

**Step 4: Normalize config and shared selectors**

Extract common configuration (datasource, pluginVersion, timezone, and time range when present) into a `config` object.

**Step 5: Replace panels with unified constructors**

Replace local helpers with `panels.*Panel()` constructors. Apply `standards.*` for units/thresholds and `themes.*` for timeseries styling. Add `id` and `gridPos` via `panels.withIdAndPatches(...)` or `+ { id, gridPos }`.
For styling and table/override patterns, load `references/visual-style-guides.md`.

**Step 6: Organize file structure**

Structure the file: imports → config → constants → variables → selectors/helpers → panel wrappers → panels → rows → annotations → dashboard. Keep all panel definitions as `local` variables in the single file.

**Step 7: Compile and verify**

Run the repo's build/compile script if available. Fix any errors. Verify panel count and layout match the original dashboard in Grafana.

## Refactor modes (quick reference)

- **Direct migration**: Remove helpers and use unified libs directly (small dashboards)
- **Wrapper pattern**: Keep helper signatures, but call unified libs internally (large dashboards)
- **Hybrid**: Mix direct + wrappers only where needed

## Guardrails

- Preserve metric semantics and layout intent.
- Avoid broad rewrites; focus on de-duplication and standards alignment.
- Keep a single file; do not create dashboard-specific lib files.
- Only update shared lib files for truly reusable components.
- Do not run `jsonnetfmt` / `jsonnet fmt` on generated Jsonnet files.

## Quality checks

- Build/compile succeeds (project script if available).
- Panel count and layout match the original dashboard.
- Units and thresholds use `standards.*`.
- Queries use `prom.*` helpers where applicable.
- No dashboard-specific lib files exist in final output.
- Preserve `__inputs` / `__requires` and manual import lines when present.
- Variables return values in Grafana; no duplicate or extra variables.
- Regex filters preserved or added where needed.
- Row membership is correct (`gridPos.y` aligns to row `gridPos.y`, and rows include panels).
- Annotations remain consistent and intentional (dashboard alerts, reboot detection, etc.).
- Dashboard metadata (`schemaVersion`, `graphTooltip`, `version`) remains intact when present.

## Minimal single-file skeleton

```jsonnet
local g = import 'github.com/grafana/grafonnet/gen/grafonnet-latest/main.libsonnet';
local helpers = import '../lib/helpers.libsonnet';
local layouts = import '../lib/layouts.libsonnet';
local panels = import '../lib/panels.libsonnet';
local prom = import '../lib/prometheus.libsonnet';
local standards = import '../lib/standards.libsonnet';
local themes = import '../lib/themes.libsonnet';

// Provisioning mode (real UID). For manual import, switch to ${DS_*}.
local DATASOURCE_UID = '<prometheus-uid>';
// local DATASOURCE_UID = '${DS_PROMETHEUS}';

local config = {
  datasource: { type: 'prometheus', uid: DATASOURCE_UID },
  pluginVersion: '12.3.0',
};

local qpsStat = panels.statPanel(
  title='QPS',
  targets=[prom.instantTarget('sum(rate(http_requests_total[1m]))', '')],
  datasource=config.datasource,
  unit=standards.units.qps,
  pluginVersion=config.pluginVersion
);

g.dashboard.new('Dashboard')
+ g.dashboard.withPanels([qpsStat])
```

## References (load as needed)

- `references/visual-style-guides.md`
- `references/full-refactor-playbook.md`
- `references/refactor-checklist.md`
- `references/examples.md`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/haomingz) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->