@grafana/create-plugin 6.2.0-canary.2233.19133609453.0 → 6.2.0-canary.2283.19173715977.0

package/src/migrations/scripts/005-react-18-3.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import { Context } from '../context.js';
+import migrate from './005-react-18-3.js';
+
+describe('005-react-18-3', () => {
+  it('should not modify anything if package.json does not exist', async () => {
+    const context = new Context('/virtual');
+    await migrate(context);
+    expect(context.listChanges()).toEqual({});
+  });
+
+  it('should not modify anything if there are no React dependencies', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          lodash: '^4.17.21',
+        },
+      })
+    );
+    const initialChanges = context.listChanges();
+    await migrate(context);
+    expect(context.listChanges()).toEqual(initialChanges);
+  });
+
+  it('should not update React if version is below 18.0.0', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^17.0.2',
+        'react-dom': '^17.0.2',
+      },
+      devDependencies: {
+        '@types/react': '^17.0.0',
+        '@types/react-dom': '^17.0.0',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+    const initialPackageJson = context.getFile('./package.json');
+
+    await migrate(context);
+
+    expect(context.getFile('./package.json')).toBe(initialPackageJson);
+  });
+
+  it('should not downgrade React 19.0.0 to 18.3.1', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^19.0.0',
+        'react-dom': '^19.0.0',
+      },
+      devDependencies: {
+        '@types/react': '^19.0.0',
+        '@types/react-dom': '^19.0.0',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^19.0.0');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^19.0.0');
+    expect(updatedPackageJson.devDependencies['@types/react']).toBe('^19.0.0');
+    expect(updatedPackageJson.devDependencies['@types/react-dom']).toBe('^19.0.0');
+  });
+
+  it('should update React 18.0.0 to 18.3.1', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '^18.0.0',
+        },
+      })
+    );
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.1');
+    expect(updatedPackageJson.devDependencies?.['@types/react']).toBe('^18.3.1');
+  });
+
+  it('should not update React if version is already 18.3.1 or higher', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^18.3.1',
+        'react-dom': '^18.3.1',
+      },
+      devDependencies: {
+        '@types/react': '^18.3.1',
+        '@types/react-dom': '^18.3.1',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+
+    await migrate(context);
+
+    // Since the versions are already 18.3.1, the migration should still run
+    // but the versions should remain 18.3.1
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.1');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^18.3.1');
+  });
+
+  it('should handle version ranges correctly', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '~18.1.0',
+          'react-dom': '18.2.0',
+        },
+      })
+    );
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.1');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^18.3.1');
+  });
+
+  it('should be idempotent', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '^18.2.0',
+          'react-dom': '^18.2.0',
+        },
+        devDependencies: {
+          '@types/react': '^18.2.0',
+          '@types/react-dom': '^18.2.0',
+        },
+      })
+    );
+    await expect(migrate).toBeIdempotent(context);
+  });
+});

package/src/migrations/scripts/005-react-18-3.ts

@@ -0,0 +1,19 @@
+import { Context } from '../context.js';
+import { addDependenciesToPackageJson, isVersionGreater } from '../utils.js';
+
+export default function migrate(context: Context) {
+  if (context.doesFileExist('package.json')) {
+    const packageJson = JSON.parse(context.getFile('package.json') || '{}');
+    if (packageJson.dependencies?.react) {
+      if (isVersionGreater(packageJson.dependencies.react, '18.0.0', true)) {
+        addDependenciesToPackageJson(context, { react: '^18.3.1' }, { '@types/react': '^18.3.1' });
+      }
+    }
+    if (packageJson.dependencies?.['react-dom']) {
+      if (isVersionGreater(packageJson.dependencies['react-dom'], '18.0.0', true)) {
+        addDependenciesToPackageJson(context, { 'react-dom': '^18.3.1' }, { '@types/react-dom': '^18.3.1' });
+      }
+    }
+  }
+  return context;
+}

package/src/{codemods/migrations → migrations}/scripts/example-migration.test.ts

@@ -1,5 +1,5 @@
 import migrate from './example-migration.js';
-import { createDefaultContext } from '../../test-utils.js';
+import { createDefaultContext } from '../test-utils.js';
 
 describe('Migration - append profile to webpack', () => {
   test('should update the package.json', async () => {

package/src/{codemods/migrations → migrations}/scripts/example-migration.ts

@@ -1,4 +1,4 @@
-import type { Context } from '../../context.js';
+import type { Context } from '../context.js';
 
 export default function migrate(context: Context): Context {
   const rawPkgJson = context.getFile('./package.json') ?? '{}';

package/src/{codemods/migrations → migrations}/utils.test.ts

@@ -1,18 +1,18 @@
 import { dirSync } from 'tmp';
-import { Context } from '../context.js';
+import { Context } from './context.js';
 import {
   addDependenciesToPackageJson,
   removeDependenciesFromPackageJson,
   flushChanges,
   formatFiles,
+  printChanges,
   readJsonFile,
   isVersionGreater,
-} from '../utils.js';
-import { printChanges } from './utils.js';
+} from './utils.js';
 import { join } from 'node:path';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
-import { output } from '../../utils/utils.console.js';
+import { output } from '../utils/utils.console.js';
 
 describe('utils', () => {
   const tmpObj = dirSync({ unsafeCleanup: true });

package/src/{codemods → migrations}/utils.ts

@@ -1,30 +1,16 @@
-/**
- * Shared utilities for codemods (migrations and additions).
- * These functions work with the Context class to modify plugin codebases.
- */
-
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { debug } from '../utils/utils.cli.js';
 import chalk from 'chalk';
+import { MigrationMeta } from './migrations.js';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerSilentInstallCmd, getPackageManagerWithFallback } from '../utils/utils.packageManager.js';
 import { execSync } from 'node:child_process';
-import { clean, coerce, gt } from 'semver';
-
-/**
- * Generic metadata type for printChanges
- */
-type ChangeMetadata = {
-  description: string;
-};
+import { clean, coerce, gt, gte } from 'semver';
 
-/**
- * Prints changes made to the context in a formatted way.
- * Works with both migrations and additions.
- */
-export function printChanges(context: Context, key: string, meta: ChangeMetadata) {
+export function printChanges(context: Context, key: string, migration: MigrationMeta) {
   const changes = context.listChanges();
   const lines = [];
 
@@ -39,7 +25,7 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 
   output.addHorizontalLine('gray');
-  output.logSingleLine(`${key} (${meta.description})`);
+  output.logSingleLine(`${key} (${migration.description})`);
 
   if (lines.length === 0) {
     output.logSingleLine('No changes were made');
@@ -48,9 +34,6 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 }
 
-/**
- * Writes all changes from the context to the filesystem.
- */
 export function flushChanges(context: Context) {
   const basePath = context.basePath;
   const changes = context.listChanges();
@@ -68,8 +51,10 @@ export function flushChanges(context: Context) {
   }
 }
 
+export const migrationsDebug = debug.extend('migrations');
+
 /**
- * Formats the files in the context using the version of prettier found in the local node_modules.
+ * Formats the files in the migration context using the version of prettier found in the local node_modules.
  * If prettier isn't installed or the file is ignored or has no parser, it will not be formatted.
  *
  * @param context - The context to format.
@@ -119,12 +104,9 @@ export async function formatFiles(context: Context) {
 }
 
 // Cache the package.json contents to avoid re-installing dependencies if the package.json hasn't changed
-// (This runs for each codemod used in an update)
+// (This runs for each migration used in an update)
 let packageJsonInstallCache: string;
 
-/**
- * Installs NPM dependencies if package.json has changed.
- */
 export function installNPMDependencies(context: Context) {
   const hasPackageJsonChanges = Object.entries(context.listChanges()).some(
     ([filePath, { changeType }]) => filePath === 'package.json' && changeType === 'update'
@@ -152,9 +134,6 @@ export function installNPMDependencies(context: Context) {
   }
 }
 
-/**
- * Reads and parses a JSON file from the context.
- */
 export function readJsonFile<T extends object = any>(context: Context, path: string): T {
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
@@ -166,9 +145,6 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   }
 }
 
-/**
- * Adds or updates dependencies in package.json, preventing downgrades.
- */
 export function addDependenciesToPackageJson(
   context: Context,
   dependencies: Record<string, string>,
@@ -184,10 +160,14 @@ export function addDependenciesToPackageJson(
     if (currentDeps[dep]) {
       if (isVersionGreater(newVersion, currentDeps[dep])) {
         currentDeps[dep] = newVersion;
+      } else {
+        migrationsDebug('would downgrade dependency %s to %s', dep, newVersion);
       }
     } else if (currentDevDeps[dep]) {
       if (isVersionGreater(newVersion, currentDevDeps[dep])) {
         currentDevDeps[dep] = newVersion;
+      } else {
+        migrationsDebug('would downgrade devDependency %s to %s', dep, newVersion);
       }
     } else {
       // Not present, add to dependencies
@@ -200,10 +180,14 @@ export function addDependenciesToPackageJson(
     if (currentDeps[dep]) {
       if (isVersionGreater(newVersion, currentDeps[dep])) {
         currentDeps[dep] = newVersion;
+      } else {
+        migrationsDebug('would downgrade dependency %s to %s', dep, newVersion);
       }
     } else if (currentDevDeps[dep]) {
       if (isVersionGreater(newVersion, currentDevDeps[dep])) {
         currentDevDeps[dep] = newVersion;
+      } else {
+        migrationsDebug('would downgrade devDependency %s to %s', dep, newVersion);
       }
     } else {
       // Not present, add to devDependencies
@@ -230,12 +214,11 @@ export function addDependenciesToPackageJson(
     ...(Object.keys(sortedDevDeps).length > 0 && { devDependencies: sortedDevDeps }),
   };
 
+  migrationsDebug('updated package.json', updatedPackageJson);
+
   context.updateFile(packageJsonPath, JSON.stringify(updatedPackageJson, null, 2));
 }
 
-/**
- * Removes dependencies from package.json.
- */
 export function removeDependenciesFromPackageJson(
   context: Context,
   dependencies: string[],
@@ -249,6 +232,7 @@ export function removeDependenciesFromPackageJson(
   for (const dep of dependencies) {
     if (currentPackageJson.dependencies?.[dep]) {
       delete currentPackageJson.dependencies[dep];
+      migrationsDebug('removed dependency %s', dep);
       hasChanges = true;
     }
   }
@@ -256,6 +240,7 @@ export function removeDependenciesFromPackageJson(
   for (const dep of devDependencies) {
     if (currentPackageJson.devDependencies?.[dep]) {
       delete currentPackageJson.devDependencies[dep];
+      migrationsDebug('removed devDependency %s', dep);
       hasChanges = true;
     }
   }
@@ -264,6 +249,8 @@ export function removeDependenciesFromPackageJson(
     return;
   }
 
+  migrationsDebug('updated package.json', currentPackageJson);
+
   context.updateFile(packageJsonPath, JSON.stringify(currentPackageJson, null, 2));
 }
 
@@ -276,8 +263,13 @@ const DIST_TAGS = {
 
 /**
  * Compares two version strings to determine if the incoming version is greater
+ *
+ * @param incomingVersion - The incoming version to compare.
+ * @param existingVersion - The existing version to compare.
+ * @param orEqualTo - Whether to include the existing version in the comparison.
+ *
  */
-export function isVersionGreater(incomingVersion: string, existingVersion: string): boolean {
+export function isVersionGreater(incomingVersion: string, existingVersion: string, orEqualTo = false) {
   const incomingIsDistTag = incomingVersion in DIST_TAGS;
   const existingIsDistTag = existingVersion in DIST_TAGS;
 
@@ -301,6 +293,10 @@ export function isVersionGreater(incomingVersion: string, existingVersion: strin
     return true;
   }
 
+  if (orEqualTo) {
+    return gte(incomingSemver, existingSemver);
+  }
+
   return gt(incomingSemver, existingSemver);
 }
 

package/src/utils/utils.config.ts

@@ -1,6 +1,5 @@
 import { argv, commandName } from './utils.cli.js';
 
-import type { AdditionFeatureName } from '../codemods/additions/additions.js';
 import { CURRENT_APP_VERSION } from './utils.version.js';
 import { DEFAULT_FEATURE_FLAGS } from '../constants.js';
 import fs from 'node:fs';
@@ -10,27 +9,16 @@ import path from 'node:path';
 import { writeFile } from 'node:fs/promises';
 import { EOL } from 'node:os';
 
-type CoreFeatureFlags = {
+export type FeatureFlags = {
   bundleGrafanaUI?: boolean;
 
   // If set to true, the plugin will be scaffolded with React Router v6. Defaults to true.
   // (Attention! We always scaffold new projects with React Router v6, so if you are changing this to `false` manually you will need to make changes to the React code as well.)
   useReactRouterV6?: boolean;
-  usePlaywright?: boolean;
   useExperimentalRspack?: boolean;
   useExperimentalUpdates?: boolean;
 };
 
-type AdditionFeatureFlags = {
-  [K in AdditionFeatureName]?: boolean;
-};
-
-export type FeatureFlags = CoreFeatureFlags & AdditionFeatureFlags;
-
-export function isFeatureEnabled(features: FeatureFlags, featureName: AdditionFeatureName): boolean {
-  return features[featureName] === true;
-}
-
 export type CreatePluginConfig = UserConfig & {
   version: string;
 };
@@ -144,18 +132,3 @@ export async function setRootConfig(configOverride: Partial<CreatePluginConfig>
 
   return updatedConfig;
 }
-
-export async function setFeatureFlag(featureName: string, enabled = true): Promise<void> {
-  const userConfig = getUserConfig() || { features: {} };
-  const userConfigPath = path.resolve(process.cwd(), '.cprc.json');
-
-  const updatedConfig = {
-    ...userConfig,
-    features: {
-      ...userConfig.features,
-      [featureName]: enabled,
-    },
-  };
-
-  await writeFile(userConfigPath, JSON.stringify(updatedConfig, null, 2) + EOL);
-}

package/templates/common/_package.json

@@ -29,7 +29,9 @@
     "@testing-library/jest-dom": "6.1.4",
     "@testing-library/react": "14.0.0",
     "@types/jest": "^29.5.0",
-    "@types/node": "^20.8.7",{{#if isAppType}}{{#unless useReactRouterV6}}
+    "@types/node": "^20.8.7",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",{{#if isAppType}}{{#unless useReactRouterV6}}
     "@types/react-router-dom": "^{{ reactRouterVersion }}",{{/unless}}{{/if}}
     "@types/testing-library__jest-dom": "5.14.8",
     "@typescript-eslint/eslint-plugin": "^8.3.0",
@@ -77,8 +79,8 @@
     "@grafana/ui": "^12.2.1",
     "@grafana/schema": "^12.2.1",{{#if_eq pluginType "scenesapp" }}
     "@grafana/scenes": "{{ scenesVersion }}",{{/if_eq}}
-    "react": "18.2.0",
-    "react-dom": "18.2.0"{{#if isAppType}},
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"{{#if isAppType}},
     "react-router-dom": "^{{ reactRouterVersion }}",
     "rxjs": "7.8.2"{{/if}}
   },

package/templates/github/workflows/cp-update.yml

@@ -1,3 +1,4 @@
+{{!-- /* 🚨 The `${{ }}` Github workflow expressions need to be escaped so they are not being interpreted by Handlebars. (this comment is going to be removed after scaffolding) 🚨 */ --}}
 name: Create Plugin Update
 
 on:
@@ -5,22 +6,16 @@ on:
   schedule:
     - cron: '0 0 1 * *' # run once a month on the 1st day
 
-# To use the default github token with the following elevated permissions make sure to check:
-# **Allow GitHub Actions to create and approve pull requests** in https://github.com/ORG_NAME/REPO_NAME/settings/actions.
-# Alternatively create a fine-grained personal access token for your repository with
-# `contents: read and write` and `pull requests: read and write` and pass it to the action.
-
-permissions:
-  contents: write
-  pull-requests: write
+# To use this workflow please create a fine-grained personal access token for your repository with:
+# `contents: read and write`
+# `pull requests: read and write`
+# `workflows: read and write`
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
       - uses: grafana/plugin-actions/create-plugin-update@create-plugin-update/v1.1.0
-        # Uncomment to use a fine-grained personal access token instead of default github token
-        # (For more info on how to generate the token see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
-        # with:
-          # Make sure to save the token in your repository secrets
-          # token: ${{ secrets.GH_PAT_TOKEN }}
+        with:
+          # Make sure to save the token in your repository secrets as `GH_PAT_TOKEN`
+          token: $\{{ secrets.GH_PAT_TOKEN }}

package/dist/codemods/additions/additions.js

@@ -1,11 +0,0 @@
-const additions = {
-  i18n: {
-    name: "i18n",
-    description: "Add internationalization (i18n) support to your plugin",
-    scriptPath: "./scripts/add-i18n.js",
-    featureName: "i18nEnabled"
-  }
-};
-var defaultAdditions = { additions };
-
-export { defaultAdditions as default };

package/dist/codemods/additions/manager.js

@@ -1,115 +0,0 @@
-import { additionsDebug, printChanges } from './utils.js';
-import defaultAdditions from './additions.js';
-import { formatFiles, flushChanges, installNPMDependencies } from '../utils.js';
-import { getConfig, isFeatureEnabled, setFeatureFlag } from '../../utils/utils.config.js';
-import { Context } from '../context.js';
-import { output } from '../../utils/utils.console.js';
-
-function getAvailableAdditions(additions = defaultAdditions.additions) {
-  return additions;
-}
-function getAdditionByName(name, additions = defaultAdditions.additions) {
-  return additions[name];
-}
-async function loadAdditionModule(addition) {
-  try {
-    const module = await import(addition.scriptPath);
-    return module;
-  } catch (error) {
-    additionsDebug('Failed to load addition module for "%s" from %s: %O', addition.name, addition.scriptPath, error);
-    return null;
-  }
-}
-async function getAdditionFlags(addition) {
-  const module = await loadAdditionModule(addition);
-  return module?.flags || [];
-}
-async function parseAdditionFlags(addition, argv) {
-  const module = await loadAdditionModule(addition);
-  if (module?.parseFlags) {
-    return module.parseFlags(argv);
-  }
-  return {};
-}
-async function validateAdditionOptions(addition, options) {
-  const flags = await getAdditionFlags(addition);
-  if (!flags || flags.length === 0) {
-    return;
-  }
-  const missingFlags = [];
-  for (const flag of flags) {
-    if (flag.required) {
-      const value = options[flag.name];
-      if (value === void 0 || value === null || Array.isArray(value) && value.length === 0) {
-        missingFlags.push(flag.name);
-      }
-    }
-  }
-  if (missingFlags.length > 0) {
-    const flagDocs = flags.filter((f) => missingFlags.includes(f.name)).map((f) => `  --${f.name}: ${f.description}`);
-    throw new Error(
-      `Missing required flag${missingFlags.length > 1 ? "s" : ""}:
-
-` + flagDocs.join("\n") + `
-
-Example: npx @grafana/create-plugin add ${addition.name} --${missingFlags[0]}=value`
-    );
-  }
-}
-async function runAdditionByName(additionName, argv) {
-  const addition = getAdditionByName(additionName);
-  if (!addition) {
-    const availableAdditions = getAvailableAdditions();
-    const additionsList = Object.keys(availableAdditions);
-    throw new Error(`Unknown addition: ${additionName}
-
-Available additions: ${additionsList.join(", ")}`);
-  }
-  const options = await parseAdditionFlags(addition, argv);
-  await validateAdditionOptions(addition, options);
-  await runAddition(addition, options);
-}
-async function runAddition(addition, additionOptions = {}) {
-  const basePath = process.cwd();
-  const config = getConfig();
-  if (isFeatureEnabled(config.features, addition.featureName)) {
-    output.log({
-      title: `Addition '${addition.name}' is already enabled`,
-      body: [`The feature flag '${addition.featureName}' is already set to true in .cprc.json.`, "No changes needed."]
-    });
-    return;
-  }
-  output.log({
-    title: `Running addition: ${addition.name}`,
-    body: [addition.description]
-  });
-  try {
-    const context = new Context(basePath);
-    const updatedContext = await executeAddition(addition, context, additionOptions);
-    additionsDebug(`context for "${addition.name} (${addition.scriptPath})":`);
-    additionsDebug("%O", updatedContext.listChanges());
-    await formatFiles(updatedContext);
-    flushChanges(updatedContext);
-    printChanges(updatedContext, addition.name, addition);
-    installNPMDependencies(updatedContext);
-    await setFeatureFlag(addition.featureName, true);
-    additionsDebug(`Set feature flag '${addition.featureName}' to true in .cprc.json`);
-    output.success({
-      title: `Successfully added ${addition.name} to your plugin.`
-    });
-  } catch (error) {
-    if (error instanceof Error) {
-      throw new Error(`Error running addition "${addition.name} (${addition.scriptPath})": ${error.message}`);
-    }
-    throw error;
-  }
-}
-async function executeAddition(addition, context, options = {}) {
-  const module = await loadAdditionModule(addition);
-  if (!module) {
-    throw new Error(`Failed to load addition module for ${addition.name}`);
-  }
-  return module.default(context, options);
-}
-
-export { executeAddition, getAdditionByName, getAdditionFlags, getAvailableAdditions, parseAdditionFlags, runAddition, runAdditionByName };