@grafana/create-plugin 7.10.0 → 7.11.0

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,29 @@
+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"
+	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,29 @@
+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 }}"
+
+	// 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: []
+	}
+}
+
+// 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/jest/utils.js

@@ -14,6 +14,8 @@ const nodeModulesToTransform = (moduleNames) => `node_modules\/(?!.*(${moduleNam
 const grafanaESModules = [
   '.pnpm', // Support using pnpm symlinked packages
   '@grafana/schema',
+  '@react-hookz/web',
+  '@ver0/deep-equal',
   '@wojtekmaj/date-utils',
   'd3',
   'd3-color',

package/templates/common/_package.json

@@ -17,7 +17,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@grafana/eslint-config": "^9.0.0",
-    "@grafana/plugin-e2e": "^3.11.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}}

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);