Foundation SDK fundamentals on Grafana Labs

The Foundation SDK builder pattern

Wed, 24 Jun 2026 15:16:44 +0200

How builders work in the Foundation SDK

With the Foundation SDK you define dashboards one step at a time with chained method calls instead of one giant config object.

Follow the builder sequence

Most dashboard code follows this flow:

Start with DashboardBuilder for dashboard-level settings.
Add each panel with PanelBuilder.
Add panel queries with DataqueryBuilder.
Export the final dashboard JSON from the completed builder chain.

Why this matters

The builder pattern has practical advantages when defining dashboards in code.

Benefit	What it means for you
Composable	Build complex dashboards from simple, reusable pieces
Readable	Chained calls read like a description of what you want
IDE-friendly	Autocomplete shows valid options at every step

SDK benefits

Wed, 24 Jun 2026 15:16:44 +0200

Main benefits of the Foundation SDK

Using the Foundation SDK provides two main benefits: strong typing and builder blocks.

Catch errors early with strong typing

The Foundation SDK is strongly typed, so the compiler can check your dashboard as you write it. Instead of discovering a broken dashboard after deployment, you see problems while you’re still writing code:

Invalid unit values: You catch invalid units during development, before they reach production dashboards.
Wrong data types for fields: If a field expects one type and gets another, the compiler fails fast with a clear error.
Missing required configuration: Required settings are enforced up front, so incomplete panel definitions do not ship.

Use option builders for complex settings

An option builder is a typed helper the SDK provides to configure one nested part of a panel or dashboard.

When configuration gets nested, option builders provide typed helpers for those subsections. They keep complex configuration readable while still giving you typed validation:

Option builder	Controls
ReduceDataOptions	How to reduce time series into single values (last, avg, sum)
VizLegendOptions	Legend display mode, placement, values shown
ThresholdsConfig	Color-coded value thresholds
FieldConfig	Per-field display overrides

Build a dashboard learning path

Wed, 24 Jun 2026 15:16:44 +0200

Learning path: Build a dashboard with the Foundation SDK

The following table describes the steps you’ll work through in the learning path.

Step	What you’ll do	Outcome
1. Set up your project	Install the Foundation SDK and create a project	A working SDK project in Go or TypeScript
2. Create a dashboard	Use DashboardBuilder to define a dashboard with UID, tags, and time range	A complete dashboard definition
3. Add panels and queries	Attach stat and time series panels with data queries	A dashboard with live visualizations
4. Export JSON	Call build() and serialize the output to a file	A deployment-ready JSON file
5. Verify the output	Inspect the JSON and optionally import into Grafana	Confirmed valid dashboard JSON

Before you start

Have these ready before you open the path:

Go 1.21+ or Node.js 18+ installed
A terminal and code editor
A Grafana Cloud account (optional, for manual import verification)

Learning path

Build a dashboard with the Foundation SDK

Welcome to the learning path that shows you how to define a Grafana dashboard as strongly typed code and export it as deployment-ready JSON.

11 min

Intermediate

Docs & blog posts

Open in Grafana Cloud

Complete this learning path directly in your Grafana Cloud stack, or in the Grafana Play stack, with an interactive learning experience.

Open in Grafana Cloud Try in Grafana Play

View on website