@grafana/create-plugin 7.17.0 → 7.19.0

package/src/commands/generate.command.ts

@@ -140,16 +140,8 @@ function getActionsForTemplateFolder({
     files = files.filter((file) => path.basename(file) !== 'npmrc');
   }
 
-  // filter out frontend bundler based on user choice
-  files = files.filter((file) => {
-    if (file.includes('webpack') && templateData.useExperimentalRspack) {
-      return false;
-    }
-    if (file.includes('rspack') && !templateData.useExperimentalRspack) {
-      return false;
-    }
-    return true;
-  });
+  // new plugins always use webpack. the rspack templates are only rendered by `add rspack`
+  files = files.filter((file) => !file.includes('rspack'));
 
   function getFileExportPath(f: string) {
     return path.relative(folderPath, path.dirname(f));

package/src/constants.ts

@@ -56,7 +56,6 @@ export const EXTRA_TEMPLATE_VARIABLES = {
 
 export const DEFAULT_FEATURE_FLAGS = {
   bundleGrafanaUI: false,
-  useExperimentalRspack: false,
   useExperimentalUpdates: true,
 };
 

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}}
-import type { RspackOptions, ExternalItemFunctionData } from '@rspack/core';{{/if}}
+{{#unless useRspack}}import type { Configuration, ExternalItemFunctionData } from 'webpack';{{/unless}}{{#if useRspack}}
+import type { ExternalItem, 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 = ExternalItem[];{{/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/PluginCssRspackPlugin.ts

@@ -0,0 +1,103 @@
+import { posix } from 'node:path';
+import { Compilation, type Compiler } from '@rspack/core';
+
+const PLUGIN_NAME = 'PluginCssRspackPlugin';
+const URL_PATTERN = /url\(\s*(["']?)([^"')]+)\1\s*\)/g;
+const CHARSET_PATTERN = /^@charset[^;]+;/;
+const MODULE_CSS_DEPENDENCY = '"./module.css"';
+// the AMD wrapper rspack writes before minification: define([deps], function(params){
+const AMD_WRAPPER_PATTERN = /^define\(\[([^\]]*)\], function\(([^)]*)\)\{/;
+
+interface PluginCssRspackPluginOptions {
+  pluginId: string;
+  publicPath: string;
+}
+
+// Prepares the CSS Grafana loads as module.css and the CSS of lazy chunks.
+export class PluginCssRspackPlugin {
+  options: PluginCssRspackPluginOptions;
+
+  constructor(options: PluginCssRspackPluginOptions) {
+    this.options = options;
+  }
+
+  apply(compiler: Compiler) {
+    const { ConcatSource, ReplaceSource } = compiler.rspack.sources;
+    const { pluginId, publicPath } = this.options;
+    const layer = `plugin-${pluginId}`;
+
+    compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+      compilation.hooks.processAssets.tap(
+        {
+          name: PLUGIN_NAME,
+          // before the CSS minimizer (PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE) so it minifies the result
+          stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
+        },
+        (assets) => {
+          // a 404 on ./module.css fails the whole plugin load, so entries without CSS drop the dependency
+          for (const [entryName, entrypoint] of compilation.entrypoints) {
+            const files = entrypoint.getFiles().map((file) => file.split('?')[0]);
+            const jsFile = `${entryName}.js`;
+            if (files.includes(`${entryName}.css`) || !assets[jsFile]) {
+              continue;
+            }
+
+            const source = assets[jsFile];
+            const js = source.source().toString();
+            if (!js.includes(MODULE_CSS_DEPENDENCY)) {
+              continue;
+            }
+
+            const wrapper = js.match(AMD_WRAPPER_PATTERN);
+            const dependencies = wrapper?.[1].split(',') ?? [];
+            const params = wrapper?.[2].split(',').map((param) => param.trim()) ?? [];
+            const index = dependencies.indexOf(MODULE_CSS_DEPENDENCY);
+            if (!wrapper || index === -1 || dependencies.length !== params.length) {
+              throw new Error(`${PLUGIN_NAME}: could not remove ./module.css from the define() wrapper in ${jsFile}.`);
+            }
+
+            // the bundle still reads the external's parameter, so it becomes an undefined local
+            const [param] = params.splice(index, 1);
+            dependencies.splice(index, 1);
+            const updated = new ReplaceSource(source);
+            updated.replace(
+              0,
+              wrapper[0].length - 1,
+              `define([${dependencies.join(',')}], function(${params.join(', ')}){var ${param};`
+            );
+            compilation.updateAsset(jsFile, updated);
+          }
+
+          for (const assetName of Object.keys(assets)) {
+            const fileName = assetName.split('?')[0];
+            if (!fileName.endsWith('.css')) {
+              continue;
+            }
+
+            const source = assets[assetName];
+            const css = source.source().toString();
+            const updated = new ReplaceSource(source);
+
+            // SystemJS and the browser resolve url() against the CSS file, not the page
+            for (const match of css.matchAll(URL_PATTERN)) {
+              const url = match[2];
+              if (!url.startsWith(publicPath)) {
+                continue;
+              }
+              const relativeUrl = posix.relative(posix.dirname(fileName), url.slice(publicPath.length));
+              const start = match.index + match[0].indexOf(url);
+              updated.replace(start, start + url.length - 1, relativeUrl);
+            }
+
+            // the layer keeps Grafana's unlayered styles winning at equal specificity. @charset must stay first
+            const charset = css.match(CHARSET_PATTERN)?.[0];
+            if (charset) {
+              updated.replace(0, charset.length - 1, '');
+            }
+            compilation.updateAsset(assetName, new ConcatSource(charset ?? '', `@layer ${layer}{`, updated, '}'));
+          }
+        }
+      );
+    });
+  }
+}