@grafana/create-plugin 7.17.0 → 7.18.0

package/src/types.ts

@@ -23,7 +23,7 @@ export type TemplateData = {
   version: string;
   bundleGrafanaUI: boolean;
   scenesVersion: string;
-  useExperimentalRspack: boolean;
+  useRspack: boolean;
   pluginExecutable?: string;
   frontendBundler: 'webpack' | 'rspack';
 };

package/src/utils/tests/utils.config.test.ts

@@ -44,6 +44,16 @@ describe('getConfig', () => {
       });
     });
 
+    it('should not let cli args switch new plugins to rspack', async () => {
+      mocks.argv = {
+        'feature-flags': 'useRspack',
+      };
+      const config = getConfig(tmpDir);
+
+      expect(config.features).toEqual(DEFAULT_FEATURE_FLAGS);
+      expect(config.features).not.toHaveProperty('useRspack');
+    });
+
     it('should override default feature flags via cli args', async () => {
       mocks.argv = {
         'feature-flags': 'bundleGrafanaUI',

package/src/utils/utils.config.ts

@@ -11,7 +11,8 @@ import { EOL } from 'node:os';
 
 export type FeatureFlags = {
   bundleGrafanaUI?: boolean;
-  useExperimentalRspack?: boolean;
+  // set by `add rspack` in .config/.cprc.json. not a default flag, so --feature-flags cannot set it
+  useRspack?: boolean;
   useExperimentalUpdates?: boolean;
 };
 

package/src/utils/utils.templates.ts

@@ -123,8 +123,8 @@ export function buildTemplateData({
     bundleGrafanaUI: features.bundleGrafanaUI ?? DEFAULT_FEATURE_FLAGS.bundleGrafanaUI,
     scenesVersion: '^8.17.0',
     pluginExecutable: pluginJson.executable,
-    useExperimentalRspack: Boolean(features.useExperimentalRspack),
-    frontendBundler: features.useExperimentalRspack ? 'rspack' : 'webpack',
+    useRspack: Boolean(features.useRspack),
+    frontendBundler: features.useRspack ? 'rspack' : 'webpack',
   };
 }
 
@@ -140,7 +140,7 @@ export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
   const { features } = getConfig();
   const currentVersion = CURRENT_APP_VERSION;
   const bundleGrafanaUI = features.bundleGrafanaUI ?? DEFAULT_FEATURE_FLAGS.bundleGrafanaUI;
-  const frontendBundler = features.useExperimentalRspack ? 'rspack' : 'webpack';
+  const frontendBundler = features.useRspack ? 'rspack' : 'webpack';
 
   let templateData: TemplateData;
 
@@ -164,7 +164,7 @@ export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
       version: currentVersion,
       bundleGrafanaUI,
       scenesVersion: '^8.17.0',
-      useExperimentalRspack: Boolean(features.useExperimentalRspack),
+      useRspack: Boolean(features.useRspack),
       frontendBundler,
     };
     // Updating or migrating a plugin

package/templates/common/.config/AGENTS/instructions.md

@@ -28,7 +28,7 @@ Your training data about the Grafana API is out of date. Use the official docume
 - **Do not change plugin ID or plugin type** in `plugin.json`.
 - Any modifications to `plugin.json` require a **restart of the Grafana server**. Remind the user of this.
 - Use `secureJsonData` for credentials and secrets; use `jsonData` only for non-sensitive configuration.
-- **You must use webpack** with the configuration provided in `.config/` for frontend builds.
+- **You must use {{frontendBundler}}** with the configuration provided in `.config/` for frontend builds.
 - **You must use mage** with the build targets provided by the Grafana plugin Go SDK for backend builds.
-- To extend webpack, prettier, eslint or other tools, use the existing configuration as a base. Follow the guide: https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md
+- To extend {{frontendBundler}}, prettier, eslint or other tools, use the existing configuration as a base. Follow the guide: https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md
 - Use **`@grafana/plugin-e2e`** for end-to-end testing. Read @./.config/AGENTS/e2e-testing.md before writing or modifying e2e tests.

package/templates/common/.config/README.md

@@ -99,6 +99,61 @@ Edit the `tsconfig.json` file in the project root in order to extend the TypeScr
 
 ---
 
+{{#if useRspack}}
+### Extending the Rspack config
+
+Follow these steps to extend the basic Rspack configuration that lives under `.config/`:
+
+#### 1. Create a new Rspack configuration file
+
+Create a new config file that is going to extend the basic one provided by Grafana.
+It can live in the project root, e.g. `rspack.config.ts`.
+
+#### 2. Merge the basic config provided by Grafana and your custom setup
+
+We are going to use [`rspack-merge`](https://github.com/rstackjs/rspack-merge) for this.
+
+```typescript
+// rspack.config.ts
+import type { Configuration } from '@rspack/core';
+import { merge } from 'rspack-merge';
+import grafanaConfig, { type Env } from './.config/rspack/rspack.config.ts';
+
+const config = async (env: Env): Promise<Configuration> => {
+  const baseConfig = await grafanaConfig(env);
+
+  return merge(baseConfig, {
+    // Add custom config here...
+    output: {
+      asyncChunks: true,
+    },
+  });
+};
+
+export default config;
+```
+
+The Rspack CLI loads this file as native ESM, so use `import.meta.dirname` instead of `__dirname` and give relative imports a `.ts` extension.
+
+#### 3. Update the `package.json` to use the new Rspack config
+
+We need to update the `scripts` in the `package.json` to use the extended Rspack configuration.
+
+**Update for `build`:**
+
+```diff
+-"build": "rspack -c ./.config/rspack/rspack.config.ts --env production",
++"build": "rspack -c ./rspack.config.ts --env production",
+```
+
+**Update for `dev`:**
+
+```diff
+-"dev": "rspack -w -c ./.config/rspack/rspack.config.ts --env development",
++"dev": "rspack -w -c ./rspack.config.ts --env development",
+```
+
+{{else}}
 ### Extending the Webpack config
 
 Follow these steps to extend the basic Webpack configuration that lives under `.config/`:
@@ -150,6 +205,7 @@ We need to update the `scripts` in the `package.json` to use the extended Webpac
 +"dev": "webpack -w -c ./webpack.config.ts --env development",
 ```
 
+{{/if}}
 ### Configure grafana image to use when running docker
 
 By default, `grafana-enterprise` will be used as the docker image for all docker related commands. If you want to override this behavior, simply alter the `docker-compose.yaml` by adding the following build arg `grafana_image`.

package/templates/common/.config/bundler/externals.ts

@@ -1,7 +1,7 @@
-{{#unless useExperimentalRspack}}import type { Configuration, ExternalItemFunctionData } from 'webpack';{{/unless}}{{#if useExperimentalRspack}}
+{{#unless useRspack}}import type { Configuration, ExternalItemFunctionData } from 'webpack';{{/unless}}{{#if useRspack}}
 import type { RspackOptions, ExternalItemFunctionData } from '@rspack/core';{{/if}}
 
-{{#unless useExperimentalRspack}} type ExternalsType = Configuration['externals'];{{/unless}}{{#if useExperimentalRspack}}type ExternalsType = RspackOptions['externals'];{{/if}}
+{{#unless useRspack}} type ExternalsType = Configuration['externals'];{{/unless}}{{#if useRspack}}type ExternalsType = RspackOptions['externals'];{{/if}}
 
 export const externals: ExternalsType = [
   // Required for dynamic publicPath resolution

package/templates/common/.config/rspack/DiagnosticsRspackPlugin.ts

@@ -0,0 +1,29 @@
+import { type Compiler } from '@rspack/core';
+import DiagnosticsWebpackPlugin from 'diagnostics-webpack-plugin';
+
+type DiagnosticsOptions = ConstructorParameters<typeof DiagnosticsWebpackPlugin>[0];
+
+// diagnostics-webpack-plugin validates its options through compiler.hooks.validate, which webpack added
+// in 5.106 and rspack doesn't have yet. a no-op hook lets the plugin run, without its options check.
+// once rspack adds the hook, delete this wrapper and use diagnostics-webpack-plugin directly
+class DiagnosticsRspackPlugin {
+  plugin: DiagnosticsWebpackPlugin;
+
+  constructor(options: DiagnosticsOptions) {
+    this.plugin = new DiagnosticsWebpackPlugin(options);
+  }
+
+  apply(compiler: Compiler) {
+    const validate = { tap: () => {} };
+    const hooks = new Proxy(compiler.hooks, {
+      get: (target, prop) => (prop === 'validate' ? validate : Reflect.get(target, prop, target)),
+    });
+    const compilerWithValidate = new Proxy(compiler, {
+      get: (target, prop) => (prop === 'hooks' ? hooks : Reflect.get(target, prop, target)),
+    });
+    // @ts-expect-error -- the plugin is typed against webpack's Compiler
+    this.plugin.apply(compilerWithValidate);
+  }
+}
+
+export default DiagnosticsRspackPlugin;

package/templates/common/.config/rspack/LicenseRspackPlugin.ts

@@ -0,0 +1,43 @@
+import { Compilation, type Compiler } from '@rspack/core';
+
+const PLUGIN_NAME = 'LicenseRspackPlugin';
+const CHUNK_LICENSE_PATTERN = /\.LICENSE\.txt$/;
+
+// This Rspack plugin works alongside SwcJsMinimizerRspackPlugin by taking all license file comments,
+// deduping them and then writing them to a single file.
+export class LicenseRspackPlugin {
+  apply(compiler: Compiler) {
+    compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+      compilation.hooks.processAssets.tap(
+        {
+          name: PLUGIN_NAME,
+          // after the minimizer (PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE) has extracted the comments
+          stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE + 1,
+        },
+        (assets) => {
+          const chunkLicenseFiles = Object.keys(assets)
+            .filter((assetName) => CHUNK_LICENSE_PATTERN.test(assetName))
+            .sort();
+
+          if (chunkLicenseFiles.length === 0) {
+            return;
+          }
+
+          const comments = new Set<string>();
+          for (const assetName of chunkLicenseFiles) {
+            const content = assets[assetName].source().toString();
+            content
+              .split(/\n{2,}/)
+              .map((comment) => comment.trim())
+              .filter(Boolean)
+              .forEach((comment) => comments.add(comment));
+            compilation.deleteAsset(assetName);
+          }
+
+          const { RawSource } = compiler.rspack.sources;
+          compilation.emitAsset('LICENSE.txt', new RawSource([...comments].join('\n\n') + '\n'));
+        }
+      );
+    });
+  }
+}

package/templates/common/.config/rspack/LiveReloadRspackPlugin.ts

@@ -0,0 +1,95 @@
+import { createServer } from 'http';
+import { type Compiler } from '@rspack/core';
+import { WebSocketServer } from 'ws';
+
+interface RspackLiveReloadPluginOptions {
+  port?: number;
+}
+
+// Serves /livereload.js and tells connected browsers to reload after every rebuild. The scaffolded
+// Grafana docker image adds <script src="http://localhost:35729/livereload.js"> to its index.html.
+class RspackLiveReloadPlugin {
+  port: number;
+  httpServer: ReturnType<typeof createServer> | null = null;
+  server: WebSocketServer | null = null;
+  // each rebuild retries the port, so live reload starts by itself once the port is free again
+  hasWarnedDisabled = false;
+
+  constructor(options: RspackLiveReloadPluginOptions = {}) {
+    this.port = options.port ?? 35729;
+  }
+
+  apply(compiler: Compiler) {
+    compiler.hooks.afterEmit.tap('RspackLiveReloadPlugin', () => {
+      this._startServer();
+      this._notifyClients();
+    });
+  }
+
+  _startServer() {
+    if (this.server) {
+      return;
+    }
+
+    this.httpServer = createServer((req, res) => {
+      if (req.url === '/livereload.js') {
+        res.writeHead(200, { 'Content-Type': 'application/javascript' });
+        res.end(this._getLiveReloadScript());
+      } else {
+        res.writeHead(404);
+        res.end('Not Found');
+      }
+    });
+
+    this.server = new WebSocketServer({ server: this.httpServer });
+    // live reload is a convenience, so a port that is already taken must not take the watch build down.
+    // ws re-emits the http server's errors on the WebSocketServer, so both need a listener
+    const disableLiveReload = (error: NodeJS.ErrnoException) => {
+      if (!this.httpServer) {
+        return;
+      }
+      if (!this.hasWarnedDisabled) {
+        this.hasWarnedDisabled = true;
+        const reason = error.code === 'EADDRINUSE' ? `port ${this.port} is already in use` : error.message;
+        console.warn(`LiveReload disabled: ${reason}. The build keeps watching without reloading the browser.`);
+      }
+      this.server?.close();
+      this.server = null;
+      this.httpServer = null;
+    };
+    this.httpServer.on('error', disableLiveReload);
+    this.server.on('error', disableLiveReload);
+    this.httpServer.listen(this.port, () => {
+      console.log(`LiveReload server started on http://localhost:${this.port}`);
+    });
+  }
+
+  _notifyClients() {
+    if (!this.server) {
+      return;
+    }
+
+    this.server.clients.forEach((client) => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(JSON.stringify({ action: 'reload' }));
+      }
+    });
+  }
+
+  _getLiveReloadScript() {
+    return `
+      (function() {
+        if (typeof WebSocket === 'undefined') return;
+        const ws = new WebSocket('ws://localhost:${this.port}');
+        ws.onmessage = function(event) {
+          const data = JSON.parse(event.data);
+          if (data.action === 'reload') {
+            window.location.reload();
+          }
+        };
+      })();
+    `;
+  }
+}
+
+export default RspackLiveReloadPlugin;

package/templates/common/.config/rspack/rspack.config.ts

@@ -5,24 +5,32 @@
  * https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations#extend-the-webpack-config
  */
 
-import rspack, { type Configuration } from '@rspack/core';
-import ESLintPlugin from 'eslint-webpack-plugin';
+import {
+  BannerPlugin,
+  Compilation,
+  CopyRspackPlugin,
+  SubresourceIntegrityPlugin,
+  SwcJsMinimizerRspackPlugin,
+  type Configuration,
+} from '@rspack/core';
 import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';
 import path from 'path';
 import ReplaceInFileWebpackPlugin from 'replace-in-file-webpack-plugin';
-import TerserPlugin from 'terser-webpack-plugin';
 import { RspackVirtualModulePlugin } from 'rspack-plugin-virtual-module';
 
-import RspackLiveReloadPlugin from './liveReloadPlugin.ts';
+import RspackLiveReloadPlugin from './LiveReloadRspackPlugin.ts';
 import { BuildModeRspackPlugin } from './BuildModeRspackPlugin.ts';
+import { LicenseRspackPlugin } from './LicenseRspackPlugin.ts';
+import DiagnosticsRspackPlugin from './DiagnosticsRspackPlugin.ts';
 import { DIST_DIR, SOURCE_DIR } from '../bundler/constants.ts';
 import { getCPConfigVersion, getEntries, getPackageJson, getPluginJson, isWSL } from '../bundler/utils.ts';
 import { externals } from '../bundler/externals.ts';
 import { copyFilePatterns } from '../bundler/copyFiles.ts';
 
-const { SubresourceIntegrityPlugin } = rspack.experiments;
 const pluginJson = getPluginJson();
+const pluginId = pluginJson.id;
 const cpVersion = getCPConfigVersion();
+const pluginVersion = getPackageJson().version;
 const virtualPublicPath = new RspackVirtualModulePlugin({
   'grafana-public-path': `
 import amdMetaModule from 'amd-module';
@@ -30,11 +38,15 @@ import amdMetaModule from 'amd-module';
 __webpack_public_path__ =
   amdMetaModule && amdMetaModule.uri
     ? amdMetaModule.uri.slice(0, amdMetaModule.uri.lastIndexOf('/') + 1)
-    : 'public/plugins/${pluginJson.id}/';
+    : 'public/plugins/${pluginId}/';
 `,
 });
 
-const config = async (env): Promise<Configuration> => {
+export type Env = {
+  [key: string]: true | string | Env;
+};
+
+const config = async (env: Env): Promise<Configuration> => {
   const baseConfig: Configuration = {
     context: path.join(process.cwd(), SOURCE_DIR),
 
@@ -117,19 +129,11 @@ const config = async (env): Promise<Configuration> => {
     optimization: {
       minimize: Boolean(env.production),
       minimizer: [
-        new TerserPlugin({
-          // Emit a single LICENSE.txt file for all comments.
-          extractComments: {
-            banner: false,
-            filename: 'LICENSE.txt',
-          },
-          terserOptions: {
-            format: {
-              comments: (_, { type, value }) => type === 'comment2' && value.trim().startsWith('[create-plugin]'),
-            },
-            compress: {
-              drop_console: ['log', 'info'],
-            },
+        new SwcJsMinimizerRspackPlugin({
+          extractComments: { banner: false },
+          minimizerOptions: {
+            format: { comments: false },
+            compress: { pure_funcs: ['console.log', 'console.info'] },
           },
         }),
       ],
@@ -145,32 +149,37 @@ const config = async (env): Promise<Configuration> => {
         type: 'amd',
       },
       path: path.resolve(process.cwd(), DIST_DIR),
-      publicPath: `public/plugins/${pluginJson.id}/`,
-      uniqueName: pluginJson.id,
+      publicPath: `public/plugins/${pluginId}/`,
+      uniqueName: pluginId,
       crossOriginLoading: 'anonymous',
     },
 
     plugins: [
       new BuildModeRspackPlugin(),
+      new LicenseRspackPlugin(),
       virtualPublicPath,
       // Insert create plugin version information into the bundle
-      new rspack.BannerPlugin({
-        banner: '/* [create-plugin] version: ' + cpVersion + ' */',
+      new BannerPlugin({
+        banner: [
+          `/* [create-plugin] version: ${cpVersion} */`,
+          `/* [create-plugin] plugin: ${pluginId}@${pluginVersion} */`,
+        ].join('\n'),
         raw: true,
         entryOnly: true,
+        // after minification to prevent banner removal and before source maps and hashes are generated so they include it.
+        stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE + 1,
       }),
-      new rspack.CopyRspackPlugin({
+      new CopyRspackPlugin({
         patterns: copyFilePatterns,
       }),
-      // Replace certain template-variables in the README and plugin.json
       new ReplaceInFileWebpackPlugin([
         {
           dir: DIST_DIR,
-          files: ['plugin.json', 'README.md'],
+          test: [/(^|\/)plugin\.json$/, /(^|\/)README\.md$/],
           rules: [
             {
               search: /\%VERSION\%/g,
-              replace: getPackageJson().version,
+              replace: pluginVersion,
             },
             {
               search: /\%TODAY\%/g,
@@ -178,7 +187,7 @@ const config = async (env): Promise<Configuration> => {
             },
             {
               search: /\%PLUGIN_ID\%/g,
-              replace: pluginJson.id,
+              replace: pluginId,
             },
           ],
         },
@@ -196,9 +205,9 @@ const config = async (env): Promise<Configuration> => {
               },
               typescript: { configFile: path.join(process.cwd(), 'tsconfig.json') },
             }),
-            new ESLintPlugin({
-              extensions: ['.ts', '.tsx'],
-              lintDirtyModulesOnly: Boolean(env.development), // don't lint on start, only lint changed files
+            new DiagnosticsRspackPlugin({
+              lintOnStart: false, // don't lint on start, only lint changed files
+              checks: [{ use: 'eslint', extensions: ['ts', 'tsx'] }],
             }),
           ]
         : []),

package/templates/common/.cprc.json

@@ -1,6 +1,5 @@
 {
   "features": {
-    "bundleGrafanaUI": {{ bundleGrafanaUI }},
-    "useExperimentalRspack": {{ useExperimentalRspack }}
+    "bundleGrafanaUI": {{ bundleGrafanaUI }}
   }
 }

package/templates/common/_package.json

@@ -20,9 +20,9 @@
     "@grafana/plugin-e2e": "^3.15.2",
     "@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}}
+    "@playwright/test": "^1.62.1",{{#if useRspack}}
+    "@rspack/core": "^2.2.0",
+    "@rspack/cli": "^2.2.0",{{/if}}
     "@stylistic/eslint-plugin": "^5.10.0",
     "@swc/core": "^1.15.0",
     "@swc/helpers": "^0.5.0",
@@ -32,19 +32,18 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",{{#if useExperimentalRspack}}
+    "@types/react-dom": "^19.0.0",{{#if useRspack}}
     "@types/ws": "^8.18.1",{{/if}}
     "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",{{#unless useExperimentalRspack}}
+    "@typescript-eslint/parser": "^8.38.0",{{#unless useRspack}}
     "copy-webpack-plugin": "^14.0.0",{{/unless}}
-    "css-loader": "^7.1.0",{{#unless useExperimentalRspack}}
-    "diagnostics-webpack-plugin": "^1.0.1",{{/unless}}
+    "css-loader": "^7.1.0",
+    "diagnostics-webpack-plugin": "^1.0.1",
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.0",
     "eslint-plugin-jsdoc": "^52.0.0",
     "eslint-plugin-react": "^7.37.0",
-    "eslint-plugin-react-hooks": "^7.1.0",{{#if useExperimentalRspack}}
-    "eslint-webpack-plugin": "^5.0.0",{{/if}}{{#unless useExperimentalRspack}}
+    "eslint-plugin-react-hooks": "^7.1.0",{{#unless useRspack}}
     "fork-ts-checker-webpack-plugin": "^9.1.0",{{/unless}}
     "identity-obj-proxy": "^3.0.0",
     "imports-loader": "^5.0.0",
@@ -53,26 +52,27 @@
     "jest-canvas-mock": "^2.5.2",
     "jest-environment-jsdom": "^30.5.0",
     "prettier": "^3.6.0",
-    "replace-in-file-webpack-plugin": "^1.0.0",{{#if useExperimentalRspack}}
+    "replace-in-file-webpack-plugin": "^1.0.0",{{#if useRspack}}
+    "rspack-merge": "^1.0.1",
     "rspack-plugin-virtual-module": "^1.0.0",{{/if}}
     "sass": "^1.89.0",
     "sass-loader": "^16.0.0",
     "semver": "^7.7.0",
-    "style-loader": "^4.0.0",{{#unless useExperimentalRspack}}
-    "swc-loader": "^0.2.0",{{/unless}}
-    "terser-webpack-plugin": "^5.3.0",
-    "ts-node": "^10.9.0",{{#if useExperimentalRspack}}
-    "ts-checker-rspack-plugin": "^1.2.0",{{/if}}
+    "style-loader": "^4.0.0",{{#unless useRspack}}
+    "swc-loader": "^0.2.0",
+    "terser-webpack-plugin": "^5.3.0",{{/unless}}
+    "ts-node": "^10.9.0",{{#if useRspack}}
+    "ts-checker-rspack-plugin": "^1.7.0",{{/if}}
     "typescript": "5.9.2",
-    "webpack": "^5.106.0"{{#unless useExperimentalRspack}},
+    "webpack": "^5.106.0"{{#unless useRspack}},
     "webpack-cli": "^6.0.0",
     "webpack-livereload-plugin": "^3.0.2",
     "webpack-subresource-integrity": "^5.1.0",
-    "webpack-virtual-modules": "^0.6.2"{{/unless}}{{#if useExperimentalRspack}},
+    "webpack-virtual-modules": "^0.6.2"{{/unless}}{{#if useRspack}},
     "ws": "^8.13.0"{{/if}}
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23"
   },
   "dependencies": {
     "@emotion/css": "11.10.6",