app-sdk-concepts

SKILL.md

Grafana App SDK Concepts

The grafana-app-sdk is a CLI + Go library for building schema-centric apps on the Grafana App Platform. Apps define resources via CUE schemas ("kinds"), generate Go + TypeScript code, and implement business logic via admission control and reconcilers.

Prerequisites

go install github.com/grafana/grafana-app-sdk/cmd/grafana-app-sdk@latest
grafana-app-sdk version   # verify

Common Workflows

Scaffold a standalone operator app

# 1. Init the project (use the Go module path)
grafana-app-sdk project init github.com/example/my-app

2. Add operator scaffolding — ASK THE USER FIRST.

They may prefer to write app.App by hand.

grafana-app-sdk project component add operator

3. Verify scaffolded layout

ls pkg/app pkg/watchers cmd/operator

Expected: app.go, watchers/.go, main.go

Common failure: forgetting `go install` updates the binary — verify with `grafana-app-sdk version` before init.

### Scaffold a grafana/apps-style app (inside `grafana/grafana`)

Only available inside the Grafana repo (or fork) — the init command detects `apps/` and `pkg/registry/apps/` at the repo root.

```bash
mkdir -p apps/my-app && cd apps/my-app
grafana-app-sdk project init github.com/grafana/grafana/apps/my-app

# Keep ONLY: kinds/ pkg/ go.mod go.sum — delete everything else.
cp apps/example/Makefile       apps/my-app/Makefile
cp apps/example/kinds/config.cue apps/my-app/kinds/config.cue   # overwrite
go work use ./apps/my-app

Then register the app inside Grafana (pkg/registry/apps/apps.go + register.go). Full walkthrough in references/deployment-modes.md.

End-to-end development loop

1. project init               → module, Makefile, kinds/
2. project kind add MyKind    → CUE kind scaffold
3. Edit kinds/*.cue           → schemas, validation, versions
4. grafana-app-sdk generate   → Go types, clients, TS types, AppManifest, CRDs
5. Implement logic            → fill in reconciler / admission stubs
6. (optional) project component add frontend

Always rerun generate after every CUE change — generated code is the API your reconciler sees.

Deployment modes (one-line table)

Mode
When to pick
Where it runs

Standalone operator
Outside Grafana repo, want your own binary
Kubernetes operator with its own webhook server

grafana/apps
Inside github.com/grafana/grafana (or fork)
In-process inside Grafana's API server

Frontend-only
UI-only app, no Go logic needed
No backend — TS types only

Full per-mode init, runtime, and wiring detail in references/deployment-modes.md.

References

references/deployment-modes.md — per-mode init, runtime semantics, grafana/apps registration walkthrough

references/project-structure.md — standalone project layout, what's hand-edited vs generated

references/cli-reference.md — every grafana-app-sdk subcommand with flags

references/specific-config.md — app.Config.SpecificConfig pattern for feature-flag-driven app config

references/local-development.md — Tilt + k3d local dev loop

references/local-config.md — local/config.yaml reference

Resources

grafana-app-sdk repo

App Platform docs