@grafana/create-plugin 7.10.1 → 7.12.0

package/templates/app-sdk/.config/app-sdk/generate-kinds.mjs

@@ -0,0 +1,138 @@
+// Runs grafana-app-sdk kind code generation from the CUE kinds in ./kinds.
+//
+// Always runs the CLI at the version pinned in VERSION below, resolved as:
+//   1. a previously obtained copy in node_modules/.cache/grafana-app-sdk/<version>/
+//   2. a fresh copy, downloaded from the official release and verified against its checksum
+//
+// A `grafana-app-sdk` on your PATH is deliberately ignored: generated code has to match the library
+// version it is compiled against, and silently generating with whatever happens to be installed makes
+// that mismatch invisible. To use your own build, set GRAFANA_APP_SDK_BIN to the binary — an explicit,
+// per-invocation override for local development.
+//
+// Downloading the CLI needs no Go toolchain. Generation itself only needs Go when codegen.goEnabled
+// is set in kinds/config.cue: the generator formats Go output with golang.org/x/tools, which shells
+// out to `go`.
+//
+// Output paths are configured in kinds/config.cue. Generated code is intended to be committed.
+
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { arch, platform, tmpdir } from 'node:os';
+
+const VERSION = 'v0.60.0';
+const REPO = 'grafana/grafana-app-sdk';
+const BIN = 'grafana-app-sdk';
+
+// Escape hatch for developing against a local CLI build, e.g. one you are changing yourself. Unlike a
+// binary that merely happens to be on PATH, setting this is a deliberate act, so it is honoured.
+const BIN_OVERRIDE = 'GRAFANA_APP_SDK_BIN';
+
+// node_modules is already gitignored, so nothing extra needs ignoring for this cache.
+const CACHE_DIR = resolve('node_modules', '.cache', 'grafana-app-sdk', VERSION);
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, { stdio: 'inherit', ...options });
+}
+
+const EXE = platform() === 'win32' ? '.exe' : '';
+
+/** Returns the release asset's platform pair, or exits if this platform has no published build. */
+function target() {
+  const goos = { linux: 'linux', darwin: 'darwin', win32: 'windows' }[platform()];
+  const goarch = { x64: 'amd64', arm64: 'arm64' }[arch()];
+
+  if (!goos || !goarch) {
+    console.error(
+      `No grafana-app-sdk release build for ${platform()}/${arch()}.\n` +
+        `Install the CLI yourself and re-run: https://github.com/${REPO}/releases`
+    );
+    process.exit(1);
+  }
+
+  return { goos, goarch };
+}
+
+async function fetchOrDie(url, what) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.error(`Failed to download ${what} (${response.status} ${response.statusText})\n  ${url}`);
+    process.exit(1);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** Downloads the release archive, verifies it against checksums.txt, and unpacks it into CACHE_DIR. */
+async function download({ goos, goarch }) {
+  // Release assets drop the leading "v" from the tag.
+  const archive = `${BIN}_${VERSION.replace(/^v/, '')}_${goos}_${goarch}.tar.gz`;
+  const base = `https://github.com/${REPO}/releases/download/${VERSION}`;
+
+  console.log(`Downloading ${BIN} ${VERSION} for ${goos}/${goarch}...`);
+  const [tarball, checksums] = await Promise.all([
+    fetchOrDie(`${base}/${archive}`, archive),
+    fetchOrDie(`${base}/checksums.txt`, 'checksums.txt'),
+  ]);
+
+  const expected = checksums
+    .toString('utf8')
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/))
+    .find(([, name]) => name === archive)?.[0];
+
+  if (!expected) {
+    console.error(`${archive} is not listed in checksums.txt; refusing to run an unverified binary.`);
+    process.exit(1);
+  }
+
+  const actual = createHash('sha256').update(tarball).digest('hex');
+  if (actual !== expected) {
+    console.error(`Checksum mismatch for ${archive}.\n  expected ${expected}\n  actual   ${actual}`);
+    process.exit(1);
+  }
+
+  // Unpack via tar(1): available on macOS/Linux and shipped with Windows 10+. The archive lays the
+  // binary flat at its root (alongside LICENSE and README.md), so extract straight into CACHE_DIR.
+  const tarPath = join(tmpdir(), `${archive}-${process.pid}`);
+  writeFileSync(tarPath, tarball);
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  const untar = run('tar', ['-xzf', tarPath, '-C', CACHE_DIR, `${BIN}${EXE}`]);
+  rmSync(tarPath, { force: true });
+  if (untar.status !== 0) {
+    console.error(`Could not unpack ${archive}. Is tar available on your PATH?`);
+    process.exit(1);
+  }
+
+  const binary = join(CACHE_DIR, `${BIN}${EXE}`);
+  chmodSync(binary, 0o755);
+
+  return binary;
+}
+
+async function resolveBinary() {
+  const override = process.env[BIN_OVERRIDE];
+  if (override) {
+    // Exit rather than falling back to the pinned version: you asked for a specific binary, so
+    // silently generating with a different one is the surprise worth avoiding.
+    if (!existsSync(override)) {
+      console.error(`${BIN_OVERRIDE} is set to ${override}, but no such file exists.`);
+      process.exit(1);
+    }
+
+    console.log(`Using ${BIN} from ${BIN_OVERRIDE}: ${override}`);
+    return resolve(override);
+  }
+
+  const cached = join(CACHE_DIR, `${BIN}${EXE}`);
+  if (existsSync(cached)) {
+    return cached;
+  }
+
+  return download(target());
+}
+
+const binary = await resolveBinary();
+const result = run(binary, ['generate', '--source', 'kinds']);
+process.exit(result.status ?? 1);

package/templates/app-sdk/.github/workflows/generate-kinds-drift.yml

@@ -0,0 +1,84 @@
+name: Kinds drift check
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'kinds/**'
+      - 'pkg/generated/**'
+      - 'src/generated/**'
+      - 'src/app-sdk-manifest.json'
+      - '.github/workflows/generate-kinds-drift.yml'
+  pull_request:
+    branches:
+      - master
+      - main
+    paths:
+      - 'kinds/**'
+      - 'pkg/generated/**'
+      - 'src/generated/**'
+      - 'src/app-sdk-manifest.json'
+      - '.github/workflows/generate-kinds-drift.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check-drift:
+    name: Check generated kinds are up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+{{#if_eq packageManagerName "pnpm"}}
+      # pnpm action uses the packageManager field in package.json to
+      # understand which version to install.
+      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+{{/if_eq}}
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: '{{ packageManagerName }}'
+
+      - name: Check for backend
+        id: check-for-backend
+        run: |
+          if [ -f "Magefile.go" ]
+          then
+            echo "has-backend=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Go environment
+        if: steps.check-for-backend.outputs.has-backend == 'true'
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Install dependencies
+        run: {{ packageManagerInstallCmd }}
+
+      - name: Cache grafana-app-sdk CLI
+        uses: actions/cache@v4
+        with:
+          path: node_modules/.cache/grafana-app-sdk
+          key: grafana-app-sdk-cli-${{ '{{' }} hashFiles('.config/app-sdk/generate-kinds.mjs') {{ '}}' }}
+
+      - name: Generate kinds
+        run: {{ packageManagerName }} run generate:kinds
+
+      - name: Fail if generated code is out of date
+        run: |
+          # Scoped to kinds/ and the generated output: installing dependencies above can itself touch
+          # files (e.g. package-lock.json, if CI's Node version differs from the one used to generate
+          # the committed lockfile), which is not kind drift and shouldn't fail this check.
+          paths="kinds src/generated pkg/generated src/app-sdk-manifest.json"
+          if [ -n "$(git status --porcelain -- $paths)" ]; then
+            echo "::error::Generated code is out of date. Run '{{ packageManagerName }} run generate:kinds' and commit the result."
+            git status --porcelain -- $paths
+            git diff --stat -- $paths
+            exit 1
+          fi

package/templates/app-sdk/kinds/README.md

@@ -0,0 +1,3 @@
+# Kinds (grafana-app-sdk)
+
+See [`.config/app-sdk/README.md`](../.config/app-sdk/README.md) for the full workflow.

package/templates/app-sdk/kinds/config.cue

@@ -0,0 +1,39 @@
+package kinds
+
+// config holds the grafana-app-sdk code generation settings, and is read by
+// `grafana-app-sdk generate` (via the default `-c config` selector) when you run
+// `{{ packageManagerName }} run generate:kinds`.
+//
+// Paths are relative to the plugin root and match the layout scaffolded by @grafana/create-plugin:
+// the frontend lives in src/.
+config: {
+	definitions: {
+		manifestVersion:  "v1alpha2"
+
+		// Do not edit this section; the generated manifest must be named exactly as below.
+		// The manifest tells Grafana which kinds and capabilities your app serves. Write it
+		// straight into src/ so the frontend build picks it up as-is.
+		manifestSchemas:  true
+		path:             "src"
+		manifestFileName: "app-sdk-manifest.json"
+		encoding:         "json"
+		// Do not generate separate files per-CRD, they are not used.
+		genCRDs: false
+	}
+
+	codegen: {
+{{#if hasBackend}}
+		// Generated Go types land alongside the plugin backend.
+		goEnabled: true
+		goGenPath: "pkg/generated/"
+{{else}}
+		// This plugin has no Go backend, so skip Go code generation entirely: only TypeScript and
+		// the definitions below are emitted, and no Go toolchain is needed to generate them.
+		goEnabled: false
+{{/if}}
+		// Generated TypeScript types land in the frontend source dir.
+		tsGenPath:                      "src/generated/"
+		enableK8sPostProcessing:        false
+		enableOperatorStatusGeneration: false
+	}
+}

package/templates/app-sdk/kinds/cue.mod/module.cue

@@ -0,0 +1,4 @@
+module: "github.com/{{ kebabCase orgName }}/{{ kebabCase pluginName }}/kinds"
+language: {
+	version: "v0.11.0"
+}

package/templates/app-sdk/kinds/example.cue

@@ -0,0 +1,32 @@
+package kinds
+
+// exampleKind holds the information about the Example kind that does not change between versions.
+// Rename this kind (and its file) to model your own resource.
+exampleKind: {
+	kind:       "Example"
+	pluralName: "Examples"
+	// Namespaced resources are created per-tenant. Use "Cluster" for global resources.
+	scope: "Namespaced"
+	// Namespaced kinds are folder-scoped by default: callers need both the Stack Role (see roles in
+	// manifest.cue) and folder access. Uncomment to opt this kind out of folder scoping.
+	// folderScoped: false
+	codegen: {
+		ts: {
+			enabled: true
+		}
+		go: {
+			enabled: true
+		}
+	}
+}
+
+// examplev1alpha1 is the v1alpha1 version of the Example kind: the common kind information plus
+// this version's schema. Edit the spec to model your resource, then re-run code generation.
+examplev1alpha1: exampleKind & {
+	schema: {
+		spec: {
+			title:       string
+			description: string
+		}
+	}
+}

package/templates/app-sdk/kinds/manifest.cue

@@ -0,0 +1,53 @@
+package kinds
+
+manifest: {
+	// appName is the unique name of your app. It is used to reference the app from other config
+	// objects, and to derive the API group your app serves (by default,
+	// LOWER(strip dashes)+".ext.grafana.app"). Set `groupOverride` if you need to pin a shorter or
+	// different group.
+	appName: "{{ pluginId }}"
+
+	// appDisplayName is the human-readable name shown for your app's roles in Grafana's role picker.
+	// Set it to something more readable than appName.
+	appDisplayName: "{{ pluginId }}"
+
+	// versions maps each version your app serves to the kinds it exposes. Version names follow the
+	// format "v<integer>" or "v<integer>(alpha|beta)<integer>".
+	versions: {
+		"v1alpha1": v1alpha1
+	}
+
+	// extraPermissions declares any additional permissions your app needs, e.g. access to kinds
+	// owned by other apps.
+	extraPermissions: {
+		accessKinds: []
+	}
+
+	// roles declares custom RBAC roles for your app. Each role name follows "<app>:<role>" and grants
+	// one of three tiers: "viewer" (read), "editor" (read + write), or "admin" (currently identical
+	// to "editor"). A role you define here is never granted to anyone without a matching entry in
+	// roleBindings below.
+	// roles: [
+	// 	{
+	// 		name:          "{{ pluginId }}:editor"
+	// 		permissionSet: "editor"
+	// 	},
+	// ]
+
+	// roleBindings attaches your app's roles to Grafana's basic roles (viewer/editor/admin), so every
+	// Grafana user with that basic role automatically inherits the matching app role.
+	// roleBindings: [
+	// 	{
+	// 		roleName:  "{{ pluginId }}:editor"
+	// 		basicRole: "editor"
+	// 	},
+	// ]
+}
+
+// v1alpha1 is the v1alpha1 version of the app's API.
+v1alpha1: {
+	// kinds lists the version-specific kind values served by this version.
+	kinds: [examplev1alpha1]
+	// served indicates whether this version is served by the API server. Defaults to true.
+	served: true
+}

package/templates/app-sdk/pkg/generated/example/v1alpha1/doc.go

@@ -0,0 +1,11 @@
+// Package v1alpha1 is a stub that exists purely so `go mod tidy` resolves its dependencies before
+// code generation has run. `generate:kinds` fills this package with its own generated files, without
+// removing this one — it's left behind, harmless, since it exports nothing.
+package v1alpha1
+
+import (
+	_ "k8s.io/apimachinery/pkg/apis/meta/v1"
+	_ "k8s.io/apimachinery/pkg/runtime"
+	_ "k8s.io/apimachinery/pkg/runtime/schema"
+	_ "k8s.io/apimachinery/pkg/types"
+)

package/templates/app-sdk/pkg/generated/manifestdata/doc.go

@@ -0,0 +1,12 @@
+// Package manifestdata is a stub that exists purely so `go mod tidy` resolves its dependencies before
+// code generation has run. `generate:kinds` fills this package with its own generated files, without
+// removing this one — it's left behind, harmless, since it exports nothing.
+package manifestdata
+
+import (
+	_ "github.com/grafana/grafana-app-sdk/app"
+	_ "github.com/grafana/grafana-app-sdk/resource"
+	_ "k8s.io/apimachinery/pkg/runtime"
+	_ "k8s.io/kube-openapi/pkg/spec3"
+	_ "k8s.io/kube-openapi/pkg/validation/spec"
+)

package/templates/app-sdk/pkg/provider/provider.go

@@ -0,0 +1,30 @@
+package provider
+
+import (
+	"github.com/grafana/grafana-app-sdk/app"
+	"github.com/grafana/grafana-app-sdk/simple"
+
+	examplev1alpha1 "github.com/{{ kebabCase orgName }}/{{ kebabCase pluginName }}/pkg/generated/example/v1alpha1"
+	"github.com/{{ kebabCase orgName }}/{{ kebabCase pluginName }}/pkg/generated/manifestdata"
+)
+
+// New returns the app.Provider, the single entry point to this package. main.go uses it to read the
+// manifest and instantiate the app.App.
+func New() app.Provider {
+	return simple.NewAppProvider(manifestdata.LocalManifest(), nil, newApp)
+}
+
+// newApp is the factory passed to simple.NewAppProvider; it builds the app.App from the resolved
+// config. Attach a Validator, Mutator, or Reconciler per kind as you need one — see
+// simple.AppManagedKind and ./.config/AGENTS/app-sdk.md.
+func newApp(cfg app.Config) (app.App, error) {
+	return simple.NewApp(simple.AppConfig{
+		Name:       "{{ pluginId }}",
+		KubeConfig: cfg.KubeConfig,
+		ManagedKinds: []simple.AppManagedKind{
+			{
+				Kind: examplev1alpha1.Kind(),
+			},
+		},
+	})
+}

package/templates/common/.config/docker-compose-base.yaml

@@ -7,7 +7,7 @@ services:
       context: .
       args:
         grafana_image: ${GRAFANA_IMAGE:-{{~grafanaImage~}} }
-        grafana_version: ${GRAFANA_VERSION:-13.1.0}
+        grafana_version: ${GRAFANA_VERSION:-13.2.2}
         development: ${DEVELOPMENT:-false}
         anonymous_auth_enabled: ${ANONYMOUS_AUTH_ENABLED:-true}
     ports:

package/templates/common/.config/eslint.config.mjs

@@ -6,7 +6,7 @@
  */
 
 import { defineConfig } from 'eslint/config';
-import grafanaConfig from '@grafana/eslint-config/flat.js';
+import grafanaConfig from '@grafana/eslint-config';
 
 export default defineConfig([
   ...grafanaConfig,

package/templates/common/.config/jest-setup.js

@@ -7,8 +7,10 @@
 
 import '@testing-library/jest-dom';
 import { TextEncoder, TextDecoder } from 'util';
+import { MessageChannel, MessagePort } from 'worker_threads';
 
-Object.assign(global, { TextDecoder, TextEncoder });
+// React 19's scheduler relies on MessageChannel, which jsdom does not implement.
+Object.assign(global, { TextDecoder, TextEncoder, MessageChannel, MessagePort });
 
 // https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom
 Object.defineProperty(global, 'matchMedia', {

package/templates/common/_package.json

@@ -16,14 +16,14 @@
   "author": "{{ sentenceCase orgName }}",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@grafana/eslint-config": "^9.0.0",
-    "@grafana/plugin-e2e": "^3.11.0",
+    "@grafana/eslint-config": "^10.0.0",
+    "@grafana/plugin-e2e": "^3.12.0",
     "@grafana/sign-plugin": "^3.3.3",
     "@grafana/tsconfig": "^2.2.0",
     "@playwright/test": "^1.62.1",{{#if useExperimentalRspack}}
     "@rspack/core": "^1.6.0",
     "@rspack/cli": "^1.6.0",{{/if}}
-    "@stylistic/eslint-plugin-ts": "^4.4.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
     "@swc/core": "^1.15.0",
     "@swc/helpers": "^0.5.0",
     "@swc/jest": "^0.2.0",
@@ -31,8 +31,8 @@
     "@testing-library/react": "^16.3.0",
     "@types/jest": "^29.5.0",
     "@types/node": "^24.0.0",
-    "@types/react": "^18.3.0",
-    "@types/react-dom": "^18.3.0",{{#if useExperimentalRspack}}
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",{{#if useExperimentalRspack}}
     "@types/ws": "^8.18.1",{{/if}}
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",{{#unless useExperimentalRspack}}
@@ -42,7 +42,7 @@
     "eslint-config-prettier": "^10.1.0",
     "eslint-plugin-jsdoc": "^52.0.0",
     "eslint-plugin-react": "^7.37.0",
-    "eslint-plugin-react-hooks": "^7.0.0",
+    "eslint-plugin-react-hooks": "^7.1.0",
     "eslint-webpack-plugin": "^5.0.0",{{#unless useExperimentalRspack}}
     "fork-ts-checker-webpack-plugin": "^9.1.0",{{/unless}}
     "glob": "^11.1.0",
@@ -74,14 +74,14 @@
   },
   "dependencies": {
     "@emotion/css": "11.10.6",
-    "@grafana/data": "13.1.0",
-    "@grafana/i18n": "13.1.0",
-    "@grafana/runtime": "13.1.0",
-    "@grafana/ui": "13.1.0",
-    "@grafana/schema": "13.1.0",{{#if_eq pluginType "scenesapp" }}
+    "@grafana/data": "13.2.2",
+    "@grafana/i18n": "13.2.2",
+    "@grafana/runtime": "13.2.2",
+    "@grafana/ui": "13.2.2",
+    "@grafana/schema": "13.2.2",{{#if_eq pluginType "scenesapp" }}
     "@grafana/scenes": "{{ scenesVersion }}",{{/if_eq}}
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0"{{#if isAppType}},
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"{{#if isAppType}},
     "react-router-dom": "^6.22.0",
     "rxjs": "7.8.2"{{/if}}
   },

package/templates/datasource/src/plugin.json

@@ -22,7 +22,7 @@
     "updated": "%TODAY%"
   },
   "dependencies": {
-    "grafanaDependency": ">=12.3.0",
+    "grafanaDependency": ">=13.2.0",
     "plugins": []
   }
 }

package/templates/panel/src/plugin.json

@@ -19,7 +19,7 @@
     "updated": "%TODAY%"
   },
   "dependencies": {
-    "grafanaDependency": ">=12.3.0",
+    "grafanaDependency": ">=13.2.0",
     "plugins": []
   }
 }

package/templates/scenes-app/src/plugin.json

@@ -52,7 +52,7 @@
     }
   ],
   "dependencies": {
-    "grafanaDependency": ">=12.3.0",
+    "grafanaDependency": ">=13.2.0",
     "plugins": []
   }
 }

package/vitest.setup.ts

@@ -28,10 +28,10 @@ const parseContent = (content?: string) => (content ? JSON.parse(content) : '');
 expect.extend({
   async toBeIdempotent(migrate: (context: Context) => Promise<Context>, context: Context) {
     const firstRun = await migrate(context);
-    const firstRunDeepCopy = structuredClone(firstRun) as unknown as ClonedContext;
+    const firstRunDeepCopy = { files: structuredClone(firstRun.listChanges()) } as unknown as ClonedContext;
 
     const secondRun = await migrate(firstRun);
-    const secondRunDeepCopy = structuredClone(secondRun) as unknown as ClonedContext;
+    const secondRunDeepCopy = { files: structuredClone(secondRun.listChanges()) } as unknown as ClonedContext;
 
     const result = await compareContexts(firstRunDeepCopy, secondRunDeepCopy);