@grafana/create-plugin 0.0.1

package/src/utils/utils.files.ts

@@ -0,0 +1,65 @@
+import path from 'path';
+import fs from 'fs';
+import { TEMPLATE_PATHS } from '../constants';
+
+// Removes common template files from the list in case they have a plugin-specific override
+export function filterOutCommonFiles(files: string[], pluginType: string) {
+  const isFileCommonAndOverriden = (file: string) =>
+    file.includes(TEMPLATE_PATHS.common) &&
+    files.includes(file.replace(TEMPLATE_PATHS.common, TEMPLATE_PATHS[pluginType]));
+
+  return files.filter((file) => (isFileCommonAndOverriden(file) ? false : true));
+}
+
+export function isFile(path: string) {
+  try {
+    return fs.lstatSync(path).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+export function readJsonFile(filename: string) {
+  if (!isFile(filename)) {
+    throw new Error(
+      `There is no "${path.basename(
+        filename
+      )}" file found at "${filename}". Make sure you run this command from a plugins root directory.`
+    );
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filename).toString());
+  } catch (error: any) {
+    error.message = `Cannot parse the "${path.basename(filename)}" file at ${filename}.`;
+    throw error;
+  }
+}
+
+export function getOnlyExistingInCwd(files: string[]) {
+  return files.filter((file) => fs.existsSync(path.join(process.cwd(), file)));
+}
+
+export function getOnlyNotExistingInCwd(files: string[]) {
+  return files.filter((file) => !fs.existsSync(path.join(process.cwd(), file)));
+}
+
+export function removeFilesInCwd(files: string[]) {
+  for (const file of files) {
+    fs.rmSync(path.join(process.cwd(), file), { recursive: true, force: true });
+  }
+}
+
+/**
+ * Returns TRUE if the file is starting with any of the provided string filters.
+ *
+ * @param file - Path of the file
+ * @param filter - A single or array of strings to filter the files by - only returns TRUE if the file starts with any of the provided filter(s).
+ */
+export function isFileStartingWith(file: string, filter: string | string[]) {
+  if (Array.isArray(filter)) {
+    return filter.some((f) => file.startsWith(f));
+  }
+
+  return file.startsWith(filter);
+}

package/src/utils/utils.handlebars.ts

@@ -0,0 +1,47 @@
+import Handlebars, { HelperOptions } from 'handlebars';
+import * as changeCase from 'change-case';
+import titleCase from 'title-case';
+import upperCase from 'upper-case';
+import lowerCase from 'lower-case';
+import { PLUGIN_TYPES } from '../constants';
+
+// Why? The `{#if}` expression in Handlebars unfortunately only accepts a boolean, which makes it hard to compare values in templates.
+export const ifEq = (a: any, b: any, options: HelperOptions) => {
+  return a === b ? options.fn(this) : options.inverse(this);
+};
+
+export const normalizeId = (pluginName: string, orgName: string, type: PLUGIN_TYPES) => {
+  const re = new RegExp(`-?${type}$`, 'i');
+  const newPluginName = pluginName.replace(re, '');
+  return changeCase.paramCase(orgName) + '-' + changeCase.paramCase(newPluginName) + `-${type}`;
+};
+
+// Needed when we are rendering the templates outside of the context of Plop but still would like to support the same helpers
+export function registerHandlebarsHelpers() {
+  const helpers = {
+    camelCase: changeCase.camelCase,
+    snakeCase: changeCase.snakeCase,
+    dotCase: changeCase.dotCase,
+    pathCase: changeCase.pathCase,
+    lowerCase: lowerCase,
+    upperCase: upperCase,
+    sentenceCase: changeCase.sentenceCase,
+    constantCase: changeCase.constantCase,
+    titleCase: titleCase,
+    dashCase: changeCase.paramCase,
+    kabobCase: changeCase.paramCase,
+    kebabCase: changeCase.paramCase,
+    properCase: changeCase.pascalCase,
+    pascalCase: changeCase.pascalCase,
+    if_eq: ifEq,
+  };
+
+  Object.keys(helpers).forEach((helperName) =>
+    Handlebars.registerHelper(helperName, helpers[helperName as keyof typeof helpers])
+  );
+}
+
+export function renderHandlebarsTemplate(template: string, data?: any) {
+  registerHandlebarsHelpers();
+  return Handlebars.compile(template)(data);
+}

package/src/utils/utils.npm.ts

@@ -0,0 +1,189 @@
+import path from 'path';
+import fs from 'fs';
+import semver from 'semver';
+import { readJsonFile } from './utils.files';
+import { renderTemplateFromFile, getTemplateData } from './utils.templates';
+import { TEMPLATE_PATHS } from '../constants';
+
+type UpdateSummary = Record<string, { prev: string | null; next: string | null }>;
+
+type UpdateOptions = {
+  onlyOutdated?: Boolean;
+};
+
+type PackageJson = {
+  scripts: Record<string, string>;
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+} & Record<string, any>;
+
+export function getPackageJson(): PackageJson {
+  return readJsonFile(path.join(process.cwd(), 'package.json'));
+}
+
+// Returns with a package.json that is generated based on the latest templates
+export function getLatestPackageJson(): PackageJson {
+  const packageJsonPath = path.join(TEMPLATE_PATHS.common, 'package.json');
+  const data = getTemplateData();
+
+  return JSON.parse(renderTemplateFromFile(packageJsonPath, data));
+}
+
+export function writePackageJson(json: PackageJson) {
+  return fs.writeFileSync(path.join(process.cwd(), 'package.json'), `${JSON.stringify(json, null, 2)}\n`);
+}
+
+export function getNpmDependencyUpdatesAsText(dependencyUpdates: UpdateSummary) {
+  return Object.entries(dependencyUpdates)
+    .map(([packageName, { prev, next }]) => {
+      // New package
+      if (!prev) {
+        return `\`${packageName}\` - \`${next}\` (new)`;
+      }
+
+      // Updated package
+      return `\`${packageName}\` - \`${prev}\` -> \`${next}\``;
+    })
+    .join('\n  ');
+}
+
+export function getPackageJsonUpdatesAsText(options: UpdateOptions = {}) {
+  let asText = '';
+  const { dependencyUpdates, devDependencyUpdates } = getPackageJsonUpdates(options);
+
+  if (Object.keys(dependencyUpdates).length > 0) {
+    asText += `\n\n  **Dependencies**\n  ${getNpmDependencyUpdatesAsText(dependencyUpdates)}`;
+  }
+
+  if (Object.keys(devDependencyUpdates).length > 0) {
+    asText += `\n\n  **Dev Dependencies**\n  ${getNpmDependencyUpdatesAsText(devDependencyUpdates)}`;
+  }
+
+  return asText;
+}
+
+export function hasNpmDependenciesToUpdate(options: UpdateOptions = {}) {
+  const { dependencyUpdates, devDependencyUpdates } = getPackageJsonUpdates(options);
+
+  return Object.keys(dependencyUpdates).length > 0 || Object.keys(devDependencyUpdates).length > 0;
+}
+
+export function updatePackageJson(options: UpdateOptions = {}) {
+  const packageJson = getPackageJson();
+  const { dependencyUpdates, devDependencyUpdates } = getPackageJsonUpdates(options);
+
+  packageJson.dependencies = updateNpmDependencies(packageJson.dependencies, dependencyUpdates);
+  packageJson.devDependencies = updateNpmDependencies(packageJson.devDependencies, devDependencyUpdates);
+  writePackageJson(packageJson);
+}
+
+export function updateNpmDependencies(
+  dependencies: Record<string, string>,
+  updateSummary: UpdateSummary
+): Record<string, string> {
+  const updatedDependencies: Record<string, string> = { ...dependencies };
+
+  for (const [packageName, summary] of Object.entries(updateSummary)) {
+    updatedDependencies[packageName] = summary.next;
+  }
+
+  return updatedDependencies;
+}
+
+export function getPackageJsonUpdates(options: UpdateOptions = {}) {
+  const packageJson = getPackageJson();
+  const newPackageJson = getLatestPackageJson();
+  const dependencies = packageJson.dependencies || {};
+  const devDependencies = packageJson.devDependencies || {};
+  const newDependencies = newPackageJson.dependencies || {};
+  const newDevDependencies = newPackageJson.devDependencies || {};
+  const dependencyUpdates = getUpdatableNpmDependencies(dependencies, newDependencies, options);
+  const devDependencyUpdates = getUpdatableNpmDependencies(devDependencies, newDevDependencies, options);
+
+  return {
+    dependencyUpdates,
+    devDependencyUpdates,
+  };
+}
+
+export function getUpdatableNpmDependencies(
+  prevDeps: Record<string, string>,
+  nextDeps: Record<string, string>,
+  options: UpdateOptions = {}
+) {
+  const updateSummary: UpdateSummary = {};
+
+  // Dependencies
+  for (const [packageName, newSemverRange] of Object.entries(nextDeps)) {
+    const currentSemverRange = prevDeps[packageName];
+
+    // New dependency
+    if (!currentSemverRange) {
+      updateSummary[packageName] = { prev: null, next: newSemverRange };
+      continue;
+    }
+
+    // No changes
+    if (newSemverRange === currentSemverRange) {
+      continue;
+    }
+
+    // Invalid semver range (e.g. when using release channels like "latest")
+    if (!semver.validRange(newSemverRange) || !semver.validRange(currentSemverRange)) {
+      updateSummary[packageName] = { prev: currentSemverRange, next: newSemverRange };
+      continue;
+    }
+
+    const newSemverVersion = semver.minVersion(newSemverRange);
+    const currentSemverVersion = semver.minVersion(currentSemverRange);
+
+    // Invalid semver version / range
+    if (!newSemverVersion || !semver.valid(newSemverVersion)) {
+      console.warn(`Skipping: invalid new semver version "${newSemverRange}" for "${packageName}"`);
+      continue;
+    }
+    if (!currentSemverVersion || !semver.valid(currentSemverVersion)) {
+      console.warn(`Skipping: invalid current semver version "${currentSemverRange}" for "${packageName}"`);
+      continue;
+    }
+
+    // Update dependencies
+    if (!options.onlyOutdated || semver.gte(newSemverVersion, currentSemverVersion)) {
+      updateSummary[packageName] = { prev: currentSemverRange, next: newSemverRange };
+      continue;
+    }
+  }
+
+  return updateSummary;
+}
+
+export function getRemovableNpmDependencies(packageNames: string[]) {
+  const { dependencies = {}, devDependencies = {} } = getPackageJson();
+
+  return packageNames.filter((packageName) => dependencies[packageName] || devDependencies[packageName]);
+}
+
+export function removeNpmDependencies(packageNames: string[], { devOnly = false } = {}) {
+  const packageJson = getPackageJson();
+
+  for (const packageName of packageNames) {
+    if (!devOnly) {
+      delete packageJson.dependencies[packageName];
+    }
+    delete packageJson.devDependencies[packageName];
+  }
+
+  writePackageJson(packageJson);
+}
+
+export function updateNpmScripts() {
+  const packageJson = getPackageJson();
+  const latestPackageJson = getLatestPackageJson();
+
+  packageJson.scripts = {
+    ...packageJson.scripts,
+    ...latestPackageJson.scripts,
+  };
+
+  writePackageJson(packageJson);
+}

package/src/utils/utils.plugin.ts

@@ -0,0 +1,9 @@
+import path from 'path';
+import { readJsonFile } from './utils.files';
+
+export function getPluginJson(srcDir?: string) {
+  const srcPath = srcDir || path.join(process.cwd(), 'src');
+  const pluginJsonPath = path.join(srcPath, 'plugin.json');
+
+  return readJsonFile(pluginJsonPath);
+}

package/src/utils/utils.templates.ts

@@ -0,0 +1,76 @@
+import glob from 'glob';
+import path from 'path';
+import fs from 'fs';
+import mkdirp from 'mkdirp';
+import { filterOutCommonFiles, isFile, isFileStartingWith } from './utils.files';
+import { renderHandlebarsTemplate } from './utils.handlebars';
+import { getPluginJson } from './utils.plugin';
+import { TEMPLATE_PATHS, EXPORT_PATH_PREFIX, EXTRA_TEMPLATE_VARIABLES } from '../constants';
+
+/**
+ *
+ * @param pluginType - The type of the plugin to get template files for (plugin-specific templates override the common ones)
+ * @param filter - (Optional) A single or array of strings to filter the files by - only the files that are starting with the filter string(s) are going to be returned.
+ */
+export function getTemplateFiles(pluginType: string, filter?: string | string[]): string[] {
+  const commonFiles = glob.sync(`${TEMPLATE_PATHS.common}/**`, { dot: true });
+  const pluginTypeSpecificFiles = glob.sync(`${TEMPLATE_PATHS[pluginType]}/**`, { dot: true });
+  const templateFiles = filterOutCommonFiles([...commonFiles, ...pluginTypeSpecificFiles], pluginType);
+
+  if (filter) {
+    return templateFiles.filter((file) => {
+      const projectRelativePath = getProjectRelativeTemplatePath(file, pluginType);
+
+      return isFileStartingWith(projectRelativePath, filter);
+    });
+  }
+
+  return templateFiles;
+}
+
+/**
+ * Returns the path of the template file that is relative to the root of the scaffolded project.
+ *
+ * @param file - The absolute path of the template file
+ * @param pluginType - The type of the plugin
+ */
+export function getProjectRelativeTemplatePath(file: string, pluginType: string) {
+  return file.replace(TEMPLATE_PATHS.common, '').replace(TEMPLATE_PATHS[pluginType], '').replace(/^\/+/, '');
+}
+
+export function compileTemplateFiles(filter?: string[], data?: any) {
+  const { type } = getPluginJson();
+
+  getTemplateFiles(type, filter).forEach((file) => compileSingleTemplateFile(type, file, data));
+}
+
+export function compileSingleTemplateFile(pluginType: string, templateFile: string, data?: any) {
+  if (!isFile(templateFile)) {
+    return;
+  }
+
+  const rendered = renderTemplateFromFile(templateFile, data);
+  const relativeExportPath = templateFile.replace(TEMPLATE_PATHS.common, '').replace(TEMPLATE_PATHS[pluginType], '');
+  const exportPath = path.join(EXPORT_PATH_PREFIX, relativeExportPath);
+
+  mkdirp.sync(path.dirname(exportPath));
+  fs.writeFileSync(exportPath, rendered);
+}
+
+export function renderTemplateFromFile(templateFile: string, data?: any) {
+  return renderHandlebarsTemplate(fs.readFileSync(templateFile).toString(), data);
+}
+
+export function getTemplateData() {
+  const pluginJson = getPluginJson();
+
+  return {
+    ...EXTRA_TEMPLATE_VARIABLES,
+    pluginId: pluginJson.id,
+    pluginName: pluginJson.name,
+    pluginDescription: pluginJson.info?.description,
+    hasBackend: Boolean(pluginJson.backend),
+    orgName: pluginJson.info?.author?.name,
+    pluginType: pluginJson.type,
+  };
+}

package/templates/_partials/backend-getting-started.md

@@ -0,0 +1,20 @@
+### Backend
+
+1. Update [Grafana plugin SDK for Go](https://grafana.com/docs/grafana/latest/developers/plugins/backend/grafana-plugin-sdk-for-go/) dependency to the latest minor version:
+
+   ```bash
+   go get -u github.com/grafana/grafana-plugin-sdk-go
+   go mod tidy
+   ```
+
+2. Build backend plugin binaries for Linux, Windows and Darwin:
+
+   ```bash
+   mage -v
+   ```
+
+3. List all available Mage targets for additional commands:
+
+   ```bash
+   mage -l
+   ```

package/templates/_partials/frontend-getting-started.md

@@ -0,0 +1,59 @@
+### Frontend
+
+1. Install dependencies
+
+   ```bash
+   yarn install
+   ```
+
+2. Build plugin in development mode or run in watch mode
+
+   ```bash
+   yarn dev
+
+   # or
+
+   yarn watch
+   ```
+
+3. Build plugin in production mode
+
+   ```bash
+   yarn build
+   ```
+
+4. Run the tests (using Jest)
+
+   ```bash
+   # Runs the tests and watches for changes
+   yarn test
+   
+   # Exists after running all the tests
+   yarn lint:ci
+   ```
+
+5. Spin up a Grafana instance and run the plugin inside it (using Docker)
+
+   ```bash
+   yarn server
+   ```
+
+6. Run the E2E tests (using Cypress)
+
+   ```bash
+   # Spin up a Grafana instance first that we tests against 
+   yarn server
+   
+   # Start the tests
+   yarn e2e
+   ```
+
+7. Run the linter
+
+   ```bash
+   yarn lint
+   
+   # or
+
+   yarn lint:fix
+   ```

package/templates/app/README.md

@@ -0,0 +1,20 @@
+# Grafana app plugin template
+
+This template is a starting point for building an app plugin for Grafana.
+
+## What are Grafana app plugins?
+
+App plugins can let you create a custom out-of-the-box monitoring experience by custom pages, nested datasources and panel plugins.
+
+## Getting started
+
+-- INSERT FRONTEND GETTING STARTED --
+{{#if hasBackend}}-- INSERT BACKEND GETTING STARTED --{{/if}}
+
+## Learn more
+
+Below you can find source code for existing app plugins and other related documentation.
+
+- [Basic app plugin example](https://github.com/grafana/grafana-plugin-examples/tree/master/examples/app-basic#readme)
+- [Plugin.json documentation](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/)
+- [How to sign a plugin?](https://grafana.com/docs/grafana/latest/developers/plugins/sign-a-plugin/)

package/templates/app/src/components/App/App.test.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { AppRootProps, PluginType } from '@grafana/data';
+import { render, screen } from '@testing-library/react';
+import { App } from './App';
+
+describe('Components/App', () => {
+  let props: AppRootProps;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    props = {
+      basename: 'a/sample-app',
+      meta: {
+        id: 'sample-app',
+        name: 'Sample App',
+        type: PluginType.app,
+        enabled: true,
+        jsonData: {},
+      },
+      query: {},
+      path: '',
+      onNavChanged: jest.fn(),
+    } as unknown as AppRootProps;
+  });
+
+  test('renders without an error"', () => {
+    render(<App {...props} />);
+
+    expect(screen.queryByText(/Hello Grafana!/i)).toBeInTheDocument();
+  });
+});

package/templates/app/src/components/App/App.tsx

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import { AppRootProps } from '@grafana/data';
+
+export class App extends React.PureComponent<AppRootProps> {
+  render() {
+    return <div className="page-container">Hello Grafana!</div>;
+  }
+}

package/templates/app/src/components/App/index.tsx

@@ -0,0 +1 @@
+export * from './App';

package/templates/app/src/components/AppConfig/AppConfig.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { PluginType } from '@grafana/data';
+import { AppConfig, AppConfigProps } from './AppConfig';
+
+describe('Components/AppConfig', () => {
+  let props: AppConfigProps;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    props = {
+      plugin: {
+        meta: {
+          id: 'sample-app',
+          name: 'Sample App',
+          type: PluginType.app,
+          enabled: true,
+          jsonData: {},
+        },
+      },
+      query: {},
+    } as unknown as AppConfigProps;
+  });
+
+  test('renders without an error"', () => {
+    render(<AppConfig plugin={props.plugin} query={props.query} />);
+
+    expect(screen.queryByText(/Enable \/ Disable/i)).toBeInTheDocument();
+  });
+
+  test('renders an "Enable" button if the plugin is disabled', () => {
+    const plugin = { meta: { ...props.plugin.meta, enabled: false } };
+
+    // @ts-ignore - We don't need to provide `addConfigPage()` and `setChannelSupport()` for these tests
+    render(<AppConfig plugin={plugin} query={props.query} />);
+
+    expect(screen.queryByText(/The plugin is currently not enabled./i)).toBeInTheDocument();
+    expect(screen.queryByText(/The plugin is currently enabled./i)).not.toBeInTheDocument();
+  });
+
+  test('renders a "Disable" button if the plugin is enabled', () => {
+    const plugin = { meta: { ...props.plugin.meta, enabled: true } };
+
+    // @ts-ignore - We don't need to provide `addConfigPage()` and `setChannelSupport()` for these tests
+    render(<AppConfig plugin={plugin} query={props.query} />);
+
+    expect(screen.queryByText(/The plugin is currently enabled./i)).toBeInTheDocument();
+    expect(screen.queryByText(/The plugin is currently not enabled./i)).not.toBeInTheDocument();
+  });
+});

package/templates/app/src/components/AppConfig/AppConfig.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import { Button, Legend, useStyles2 } from '@grafana/ui';
+import { PluginConfigPageProps, AppPluginMeta, PluginMeta, GrafanaTheme2 } from '@grafana/data';
+import { getBackendSrv } from '@grafana/runtime';
+import { css } from '@emotion/css';
+import { lastValueFrom } from 'rxjs';
+
+export type AppPluginSettings = {};
+
+export interface AppConfigProps extends PluginConfigPageProps<AppPluginMeta<AppPluginSettings>> {}
+
+export const AppConfig = ({ plugin }: AppConfigProps) => {
+  const s = useStyles2(getStyles);
+  const { enabled, jsonData } = plugin.meta;
+
+  return (
+    <div className="gf-form-group">
+      <div>
+        {/* Enable the plugin */}
+        <Legend>Enable / Disable</Legend>
+        {!enabled && (
+          <>
+            <div className={s.colorWeak}>The plugin is currently not enabled.</div>
+            <Button
+              className={s.marginTop}
+              variant="primary"
+              onClick={() =>
+                updatePluginAndReload(plugin.meta.id, {
+                  enabled: true,
+                  pinned: true,
+                  jsonData,
+                })
+              }
+            >
+              Enable plugin
+            </Button>
+          </>
+        )}
+
+        {/* Disable the plugin */}
+        {enabled && (
+          <>
+            <div className={s.colorWeak}>The plugin is currently enabled.</div>
+            <Button
+              className={s.marginTop}
+              variant="destructive"
+              onClick={() =>
+                updatePluginAndReload(plugin.meta.id, {
+                  enabled: false,
+                  pinned: false,
+                  jsonData,
+                })
+              }
+            >
+              Disable plugin
+            </Button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};
+
+const getStyles = (theme: GrafanaTheme2) => ({
+  colorWeak: css`
+    color: ${theme.colors.text.secondary};
+  `,
+  marginTop: css`
+    margin-top: ${theme.spacing(3)};
+  `,
+});
+
+const updatePluginAndReload = async (pluginId: string, data: Partial<PluginMeta>) => {
+  try {
+    await updatePlugin(pluginId, data);
+
+    // Reloading the page as the changes made here wouldn't be propagated to the actual plugin otherwise.
+    // This is not ideal, however unfortunately currently there is no supported way for updating the plugin state.
+    window.location.reload();
+  } catch (e) {
+    console.error('Error while updating the plugin', e);
+  }
+};
+
+export const updatePlugin = async (pluginId: string, data: Partial<PluginMeta>) => {
+  const response = getBackendSrv().fetch({
+    url: `/api/plugins/${pluginId}/settings`,
+    method: 'POST',
+    data,
+  });
+  return lastValueFrom(response);
+};

package/templates/app/src/components/AppConfig/index.tsx

@@ -0,0 +1 @@
+export * from './AppConfig';