app-sdk-concepts
Use when starting any grafana-app-sdk work — scaffolding a Grafana app, initializing a Grafana App Platform app, picking a deployment mode (standalone operator / grafana/apps / frontend-only), wiring app-specific config, or onboarding to the SDK. Covers `grafana-app-sdk` CLI install, `project init` per deployment mode, project layout, the schema-centric workflow (CUE kinds → generated code → reconciler/admission logic), and `SpecificConfig` for env-driven app configuration. Use even if the user just says "make a new app", "Grafana app platform", "kinds and watchers", "operator scaffold", or asks about `apps/` inside the Grafana repo, without naming the SDK explicitly.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 12
- Forks
- 5
01 前言 Front Matter
- name
- app-sdk-concepts
- license
- Apache-2.0
- description
- Use when starting any grafana-app-sdk work — scaffolding a Grafana app, initializing a Grafana App Platform app, picking a deployment mode (standalone operator / grafana/apps / frontend-only), wiring app-specific config, or onboarding to the SDK. Covers `grafana-app-sdk` CLI install, `project init` per deployment mode, project layout, the schema-centric workflow (CUE kinds → generated code → reconciler/admission logic), and `SpecificConfig` for env-driven app configuration. Use even if the user just says "make a new app", "Grafana app platform", "kinds and watchers", "operator scaffold", or asks about `apps/` inside the Grafana repo, without naming the SDK explicitly.
02 资源文件 7
- 参考文档agents/openai.yaml168 B
- 参考文档references/cli-reference.md8.6 KB
- 参考文档references/deployment-modes.md5.4 KB
- 参考文档references/local-config.md4.2 KB
- 参考文档references/local-development.md6.5 KB
- 参考文档references/project-structure.md1.6 KB
- 参考文档references/specific-config.md975 B
03 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/<kind>.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.
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 walkthroughreferences/project-structure.md— standalone project layout, what's hand-edited vs generatedreferences/cli-reference.md— everygrafana-app-sdksubcommand with flagsreferences/specific-config.md—app.Config.SpecificConfigpattern for feature-flag-driven app configreferences/local-development.md— Tilt + k3d local dev loopreferences/local-config.md—local/config.yamlreference
Resources
04 同仓库更多 Skills
zarr-python
Stores and queries chunked N-D scientific arrays with Zarr-Python 3, including codecs, sharding, S3/GCS storage, and NumPy/Dask/Xarray integration. Use for array layout, bounded I/O, format migration, or scientific metadata preservation.
yeet
Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.
xarray
N-dimensional labeled arrays and datasets in Python. Built on top of NumPy and Dask. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, making data analysis in physical sciences more intuitive and less error-prone. Use for working with multi-dimensional scientific data, NetCDF/GRIB/Zarr files, climate/weather/oceanographic datasets, remote sensing, geospatial imaging, large out-of-memory datasets with Dask, and labeled array operations.
writing-mstest-tests
Use when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for "review" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected/actual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext/lifecycle; timeout/cancellation; OS/CI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest/non-.NET code.
wgs-prs
End-to-end WGS to polygenic risk score pipeline. Takes paired-end FASTQ files (or a pre-existing VCF) through nf-core/sarek for variant calling, applies VCF QC (normalisation, hard filtering, Ti/Tv and Het/Hom checks), then computes polygenic risk scores via the PGS Catalog. Fills the FASTQ to VCF gap upstream of the gwas-prs skill.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.