@grafana/create-plugin 7.18.0 → 7.19.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [7.19.0](https://github.com/grafana/plugin-tools/compare/@grafana/create-plugin@7.18.0...@grafana/create-plugin@7.19.0) (2026-11-02)
+
+
+### Features
+
+* extract CSS into separate files in rspack builds ([#3040](https://github.com/grafana/plugin-tools/issues/3040)) ([2fd22de](https://github.com/grafana/plugin-tools/commit/2fd22de25721a0bfc718e266b6cc1bcddcd37457))
+
 ## [7.18.0](https://github.com/grafana/plugin-tools/compare/@grafana/create-plugin@7.17.0...@grafana/create-plugin@7.18.0) (2026-11-02)
 
 

package/dist/codemods/additions/prompts/rspack.md

@@ -24,8 +24,8 @@ What is left is the plugin's own build customisation, which needs judgement to p
    - No plugin code builds a runtime URL to a file the new base config no longer copies into `dist` (see step 6).
 3. Otherwise, work out the starting point:
    - **From webpack**: there is a root `webpack.config.*`, or `rspack.config.ts` contains the `[rspack]` error. Follow all the steps below.
-   - **From experimental rspack**: there is a root `rspack.config.ts` without the `[rspack]` error, and there is no root `webpack.config.*`. The config is already rspack but may use rspack 1 APIs. Skip step 2 and upgrade that file in place using steps 3 to 7.
-   - **No custom config**: there is neither a root `webpack.config.*` nor a root `rspack.config.ts`. Only step 6 applies.
+   - **From experimental rspack**: there is a root `rspack.config.ts` without the `[rspack]` error, and there is no root `webpack.config.*`. The config is already rspack but may use rspack 1 APIs. Skip step 2 and upgrade that file in place using steps 3 to 8.
+   - **No custom config**: there is neither a root `webpack.config.*` nor a root `rspack.config.ts`. Only steps 6 and 7 apply.
 
 With a custom config, the build is expected to fail at this point with the `[rspack]` error. Do not chase build errors one by one; the steps below drive the work.
 
@@ -50,8 +50,7 @@ With a custom config, the build is expected to fail at this point with the `[rsp
    | `fork-ts-checker-webpack-plugin`                                                                                                                                                 | `TsCheckerRspackPlugin` from `ts-checker-rspack-plugin`                                                                                                                                                                                           |
    | `eslint-webpack-plugin`, `eslint-rspack-plugin`, or `diagnostics-webpack-plugin` used directly                                                                                   | `DiagnosticsRspackPlugin` from `./.config/rspack/DiagnosticsRspackPlugin.ts`, with `checks: [{ use: 'eslint', ... }]`. It wraps `diagnostics-webpack-plugin`, which fails under rspack on its own. `failOnError` and `severity` become `reportAs` |
    | `webpack-livereload-plugin`                                                                                                                                                      | already in the base config for development builds                                                                                                                                                                                                 |
-   | `mini-css-extract-plugin`                                                                                                                                                        | `CssExtractRspackPlugin` from `@rspack/core`                                                                                                                                                                                                      |
-   | `css-minimizer-webpack-plugin`                                                                                                                                                   | `LightningCssMinimizerRspackPlugin` from `@rspack/core`                                                                                                                                                                                           |
+   | `mini-css-extract-plugin`, `css-minimizer-webpack-plugin`                                                                                                                        | not needed: the base config already emits CSS files and minifies them with `LightningCssMinimizerRspackPlugin`                                                                                                                                    |
    | `terser-webpack-plugin` added by the plugin                                                                                                                                      | `SwcJsMinimizerRspackPlugin` from `@rspack/core`, or keep terser                                                                                                                                                                                  |
    | `html-webpack-plugin`                                                                                                                                                            | `HtmlRspackPlugin` from `@rspack/core`                                                                                                                                                                                                            |
    | `tsconfig-paths-webpack-plugin`                                                                                                                                                  | the `resolve.tsConfig` option                                                                                                                                                                                                                     |
@@ -63,6 +62,7 @@ With a custom config, the build is expected to fail at this point with the `[rsp
 
 4. Fix code that depends on how the base config is built. Each of these works in webpack and silently does nothing, or throws, in rspack:
    - **Looking up a rule by loader name**, such as `rule.use.loader === 'swc-loader'`. The base config uses `builtin:swc-loader`, so match that. Prefer merging a rule over mutating the base one.
+   - **CSS rules**: the base config builds CSS natively with `type: 'css/auto'`. It has no `style-loader`, `css-loader` or `mini-css-extract-plugin`, and it emits `module.css`. Remove `style-loader`, `css-loader` and `mini-css-extract-plugin` from ported rules. Keep loaders that transform the CSS, such as `postcss-loader` for Tailwind or `sass-loader`, as `use` on a rule with `type: 'css/auto'`. Move `css-loader` `modules` options to `module.parser['css/auto']` and `module.generator['css/auto']`. A `mergeWithRules` keyed on `use.loader: 'style-loader'` or `'css-loader'` matches nothing.
    - **Looking up a plugin with `instanceof` or `constructor.name`** against webpack plugin classes, such as `CopyWebpackPlugin` or `LiveReloadPlugin`. Use the rspack class names, or merge instead of mutating.
    - **`webpack-merge` rules keyed on old names**: `unique('plugins', ['CopyPlugin'], …)` or `mergeWithRules` matching `use.loader: 'swc-loader'`. Update the names.
    - **A `filter` function on a `CopyWebpackPlugin` pattern**. `CopyRspackPlugin` has no `filter`; use `globOptions: { ignore: [...] }`. The base copy patterns come from `.config/bundler/copyFiles.ts`.
@@ -85,30 +85,32 @@ With a custom config, the build is expected to fail at this point with the `[rsp
    - The base asset rules only cover `png`, `jpg`, `jpeg`, `gif`, `svg` and font files. For other types, such as `webp`, add an `asset/resource` rule in `rspack.config.ts`.
    - Copy the file instead of importing it when the path is built at runtime, for example `` `${base}/img/${name}.svg` ``, or when something outside the bundle refers to it, such as the README, documentation or another plugin. Add a `CopyRspackPlugin` to `rspack.config.ts` for just those files, with a comment saying why they are copied. Do not copy whole folders to be safe: every copied file ends up in the plugin archive.
 
-7. If something has no rspack equivalent, for example a monkey-patch of webpack internals, a custom `RuntimeModule` plugin, or an SWC Wasm plugin whose ABI does not match rspack's built-in SWC:
+7. List the plugin's own global stylesheets: `.css`, `.scss` and `.sass` files outside `node_modules` whose names don't end in `.module.css`, `.module.scss` or `.module.sass`. The base config loads them as plain CSS, so their rules apply to every page in Grafana, not only the plugin. Do not convert them to CSS modules or change the code that imports them. Name each file in your report, so the user can decide whether to scope it.
+
+8. If something has no rspack equivalent, for example a monkey-patch of webpack internals, a custom `RuntimeModule` plugin, or an SWC Wasm plugin whose ABI does not match rspack's built-in SWC:
    - Port what you can.
    - Comment out the rest, keeping the original code in the comment, so it does not run and the build does not fail.
    - Put a `TODO(rspack):` comment above it that says what the code did, why it has no direct equivalent, and a suggested approach.
    - Never drop it silently.
 
-8. Fix any script the codemod reported as not rewritten so it calls `rspack` with `./rspack.config.ts` or `./.config/rspack/rspack.config.ts`, keeping its other commands and flags. Remove the CLI flags rspack does not support: `--progress`, `--color`, `--bail`, `--output-pathinfo`.
+9. Fix any script the codemod reported as not rewritten so it calls `rspack` with `./rspack.config.ts` or `./.config/rspack/rspack.config.ts`, keeping its other commands and flags. Remove the CLI flags rspack does not support: `--progress`, `--color`, `--bail`, `--output-pathinfo`.
 
-9. For each file the codemod kept in `.config/webpack/`, copy what is still needed to a folder outside `.config/` (for example `build/`), port it to rspack, and update the imports. Do not delete the originals; list them so the user can delete them.
+10. For each file the codemod kept in `.config/webpack/`, copy what is still needed to a folder outside `.config/` (for example `build/`), port it to rspack, and update the imports. Do not delete the originals; list them so the user can delete them.
 
-10. Remove the webpack packages the codemod kept, once nothing imports them. Keep `webpack` itself if anything still imports it.
+11. Remove the webpack packages the codemod kept, once nothing imports them. Keep `webpack` itself if anything still imports it.
 
-11. Delete the root `webpack.config.*` and its helper files once everything in them is ported or commented with `TODO(rspack):`.
+12. Delete the root `webpack.config.*` and its helper files once everything in them is ported or commented with `TODO(rspack):`.
 
 ## Verify
 
 1. Install dependencies, then run the `typecheck` and `build` scripts. Both must pass, with any unportable code commented out.
-2. Check that `dist/` contains `module.js`, `plugin.json`, and every file that plugin code or `plugin.json` refers to by path at runtime. Imported images are hashed, so their names change.
+2. Check that `dist/` contains `module.js`, `plugin.json`, `module.css` if the entry code imports any CSS, and every file that plugin code or `plugin.json` refers to by path at runtime. Imported images are hashed, so their names change.
 3. Run the `dev` script briefly and check that it compiles and keeps watching.
 4. Fix only breakage caused by this migration.
 
 ## Report
 
-End with a list of every `TODO(rspack):` comment you added (file, line, one-line reason), every file the user should delete, any duplicate transpiler rule you removed or kept (step 5), every image reference you changed to an import or kept as a copy (step 6), and any `exportsPresence` errors you left for the user.
+End with a list of every `TODO(rspack):` comment you added (file, line, one-line reason), every file the user should delete, any duplicate transpiler rule you removed or kept (step 5), every image reference you changed to an import or kept as a copy (step 6), every global stylesheet (step 7), and any `exportsPresence` errors you left for the user.
 
 ## Out of scope
 

package/dist/codemods/additions/scripts/rspack.js

@@ -15,7 +15,8 @@ const RSPACK_CONFIG_FILES = [
   ".config/rspack/BuildModeRspackPlugin.ts",
   ".config/rspack/LiveReloadRspackPlugin.ts",
   ".config/rspack/LicenseRspackPlugin.ts",
-  ".config/rspack/DiagnosticsRspackPlugin.ts"
+  ".config/rspack/DiagnosticsRspackPlugin.ts",
+  ".config/rspack/PluginCssRspackPlugin.ts"
 ];
 const RETIRED_RSPACK_FILES = [".config/rspack/liveReloadPlugin.ts"];
 const DOC_FILES = [".config/AGENTS/instructions.md", ".config/README.md"];
@@ -58,6 +59,7 @@ function rspack(context) {
   replaceExperimentalRspackFlag(context, { enable: true });
   followUps.push(...addRootRspackConfigStub(context));
   followUps.push(...updatePackageJson(context));
+  followUps.push(...raiseGrafanaDependency(context));
   followUps.push(...deleteWebpackTemplateFiles(context));
   reportFollowUps(context, followUps);
   return context;
@@ -171,6 +173,28 @@ function raiseNodeEngine(context) {
   const engines = { ...packageJson.engines, node: ">=22.23" };
   context.updateFile("package.json", JSON.stringify({ ...packageJson, engines }, null, 2));
 }
+const MIN_GRAFANA_VERSION = "12.2.5";
+function raiseGrafanaDependency(context) {
+  const pluginJsonPath = "src/plugin.json";
+  if (!context.doesFileExist(pluginJsonPath)) {
+    return [];
+  }
+  const pluginJson = readJsonFile(context, pluginJsonPath);
+  const grafanaRange = pluginJson.dependencies?.grafanaDependency;
+  if (typeof grafanaRange !== "string" || !validRange(grafanaRange)) {
+    return [];
+  }
+  const lowestAllowedVersion = minVersion(grafanaRange);
+  if (!lowestAllowedVersion || !lt(lowestAllowedVersion, MIN_GRAFANA_VERSION)) {
+    return [];
+  }
+  const grafanaDependency = `>=${MIN_GRAFANA_VERSION}`;
+  const dependencies = { ...pluginJson.dependencies, grafanaDependency };
+  context.updateFile(pluginJsonPath, JSON.stringify({ ...pluginJson, dependencies }, null, 2));
+  return [
+    `Raised grafanaDependency in src/plugin.json from ${grafanaRange} to ${grafanaDependency}. Earlier versions of Grafana do not provide react/jsx-runtime, which the rspack config loads from Grafana.`
+  ];
+}
 const LOCKED_RSPACK_PACKAGE_PATTERN = /(^|\/)node_modules\/@rspack\//;
 function dropLockedRspackOnePackages(context) {
   if (!context.doesFileExist("package-lock.json")) {
@@ -220,14 +244,17 @@ const RSPACK_DEV_DEPENDENCIES = [
   "rspack-merge",
   "rspack-plugin-virtual-module",
   "ts-checker-rspack-plugin",
-  // style-loader and imports-loader still need webpack, and diagnostics-webpack-plugin peers on webpack ^5.106
+  // diagnostics-webpack-plugin peers on webpack ^5.106
   "webpack",
   "ws"
 ];
 const WEBPACK_ONLY_DEV_DEPENDENCIES = [
   "copy-webpack-plugin",
+  "css-loader",
   "eslint-webpack-plugin",
   "fork-ts-checker-webpack-plugin",
+  "imports-loader",
+  "style-loader",
   "swc-loader",
   "terser-webpack-plugin",
   "webpack-cli",
@@ -235,15 +262,7 @@ const WEBPACK_ONLY_DEV_DEPENDENCIES = [
   "webpack-subresource-integrity",
   "webpack-virtual-modules"
 ];
-const BASE_CONFIG_DEV_DEPENDENCIES = [
-  "@swc/helpers",
-  "css-loader",
-  "imports-loader",
-  "replace-in-file-webpack-plugin",
-  "sass",
-  "sass-loader",
-  "style-loader"
-];
+const BASE_CONFIG_DEV_DEPENDENCIES = ["@swc/helpers", "replace-in-file-webpack-plugin", "sass", "sass-loader"];
 const PACKAGE_JSON_TEMPLATE_DATA = {
   ...RSPACK_TEMPLATE_DATA_OVERRIDES,
   pluginName: "plugin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "7.18.0",
+  "version": "7.19.0",
   "repository": {
     "type": "git",
     "directory": "packages/create-plugin",

package/src/codemods/additions/prompts/rspack.md

@@ -24,8 +24,8 @@ What is left is the plugin's own build customisation, which needs judgement to p
    - No plugin code builds a runtime URL to a file the new base config no longer copies into `dist` (see step 6).
 3. Otherwise, work out the starting point:
    - **From webpack**: there is a root `webpack.config.*`, or `rspack.config.ts` contains the `[rspack]` error. Follow all the steps below.
-   - **From experimental rspack**: there is a root `rspack.config.ts` without the `[rspack]` error, and there is no root `webpack.config.*`. The config is already rspack but may use rspack 1 APIs. Skip step 2 and upgrade that file in place using steps 3 to 7.
-   - **No custom config**: there is neither a root `webpack.config.*` nor a root `rspack.config.ts`. Only step 6 applies.
+   - **From experimental rspack**: there is a root `rspack.config.ts` without the `[rspack]` error, and there is no root `webpack.config.*`. The config is already rspack but may use rspack 1 APIs. Skip step 2 and upgrade that file in place using steps 3 to 8.
+   - **No custom config**: there is neither a root `webpack.config.*` nor a root `rspack.config.ts`. Only steps 6 and 7 apply.
 
 With a custom config, the build is expected to fail at this point with the `[rspack]` error. Do not chase build errors one by one; the steps below drive the work.
 
@@ -50,8 +50,7 @@ With a custom config, the build is expected to fail at this point with the `[rsp
    | `fork-ts-checker-webpack-plugin`                                                                                                                                                 | `TsCheckerRspackPlugin` from `ts-checker-rspack-plugin`                                                                                                                                                                                           |
    | `eslint-webpack-plugin`, `eslint-rspack-plugin`, or `diagnostics-webpack-plugin` used directly                                                                                   | `DiagnosticsRspackPlugin` from `./.config/rspack/DiagnosticsRspackPlugin.ts`, with `checks: [{ use: 'eslint', ... }]`. It wraps `diagnostics-webpack-plugin`, which fails under rspack on its own. `failOnError` and `severity` become `reportAs` |
    | `webpack-livereload-plugin`                                                                                                                                                      | already in the base config for development builds                                                                                                                                                                                                 |
-   | `mini-css-extract-plugin`                                                                                                                                                        | `CssExtractRspackPlugin` from `@rspack/core`                                                                                                                                                                                                      |
-   | `css-minimizer-webpack-plugin`                                                                                                                                                   | `LightningCssMinimizerRspackPlugin` from `@rspack/core`                                                                                                                                                                                           |
+   | `mini-css-extract-plugin`, `css-minimizer-webpack-plugin`                                                                                                                        | not needed: the base config already emits CSS files and minifies them with `LightningCssMinimizerRspackPlugin`                                                                                                                                    |
    | `terser-webpack-plugin` added by the plugin                                                                                                                                      | `SwcJsMinimizerRspackPlugin` from `@rspack/core`, or keep terser                                                                                                                                                                                  |
    | `html-webpack-plugin`                                                                                                                                                            | `HtmlRspackPlugin` from `@rspack/core`                                                                                                                                                                                                            |
    | `tsconfig-paths-webpack-plugin`                                                                                                                                                  | the `resolve.tsConfig` option                                                                                                                                                                                                                     |
@@ -63,6 +62,7 @@ With a custom config, the build is expected to fail at this point with the `[rsp
 
 4. Fix code that depends on how the base config is built. Each of these works in webpack and silently does nothing, or throws, in rspack:
    - **Looking up a rule by loader name**, such as `rule.use.loader === 'swc-loader'`. The base config uses `builtin:swc-loader`, so match that. Prefer merging a rule over mutating the base one.
+   - **CSS rules**: the base config builds CSS natively with `type: 'css/auto'`. It has no `style-loader`, `css-loader` or `mini-css-extract-plugin`, and it emits `module.css`. Remove `style-loader`, `css-loader` and `mini-css-extract-plugin` from ported rules. Keep loaders that transform the CSS, such as `postcss-loader` for Tailwind or `sass-loader`, as `use` on a rule with `type: 'css/auto'`. Move `css-loader` `modules` options to `module.parser['css/auto']` and `module.generator['css/auto']`. A `mergeWithRules` keyed on `use.loader: 'style-loader'` or `'css-loader'` matches nothing.
    - **Looking up a plugin with `instanceof` or `constructor.name`** against webpack plugin classes, such as `CopyWebpackPlugin` or `LiveReloadPlugin`. Use the rspack class names, or merge instead of mutating.
    - **`webpack-merge` rules keyed on old names**: `unique('plugins', ['CopyPlugin'], …)` or `mergeWithRules` matching `use.loader: 'swc-loader'`. Update the names.
    - **A `filter` function on a `CopyWebpackPlugin` pattern**. `CopyRspackPlugin` has no `filter`; use `globOptions: { ignore: [...] }`. The base copy patterns come from `.config/bundler/copyFiles.ts`.
@@ -85,30 +85,32 @@ With a custom config, the build is expected to fail at this point with the `[rsp
    - The base asset rules only cover `png`, `jpg`, `jpeg`, `gif`, `svg` and font files. For other types, such as `webp`, add an `asset/resource` rule in `rspack.config.ts`.
    - Copy the file instead of importing it when the path is built at runtime, for example `` `${base}/img/${name}.svg` ``, or when something outside the bundle refers to it, such as the README, documentation or another plugin. Add a `CopyRspackPlugin` to `rspack.config.ts` for just those files, with a comment saying why they are copied. Do not copy whole folders to be safe: every copied file ends up in the plugin archive.
 
-7. If something has no rspack equivalent, for example a monkey-patch of webpack internals, a custom `RuntimeModule` plugin, or an SWC Wasm plugin whose ABI does not match rspack's built-in SWC:
+7. List the plugin's own global stylesheets: `.css`, `.scss` and `.sass` files outside `node_modules` whose names don't end in `.module.css`, `.module.scss` or `.module.sass`. The base config loads them as plain CSS, so their rules apply to every page in Grafana, not only the plugin. Do not convert them to CSS modules or change the code that imports them. Name each file in your report, so the user can decide whether to scope it.
+
+8. If something has no rspack equivalent, for example a monkey-patch of webpack internals, a custom `RuntimeModule` plugin, or an SWC Wasm plugin whose ABI does not match rspack's built-in SWC:
    - Port what you can.
    - Comment out the rest, keeping the original code in the comment, so it does not run and the build does not fail.
    - Put a `TODO(rspack):` comment above it that says what the code did, why it has no direct equivalent, and a suggested approach.
    - Never drop it silently.
 
-8. Fix any script the codemod reported as not rewritten so it calls `rspack` with `./rspack.config.ts` or `./.config/rspack/rspack.config.ts`, keeping its other commands and flags. Remove the CLI flags rspack does not support: `--progress`, `--color`, `--bail`, `--output-pathinfo`.
+9. Fix any script the codemod reported as not rewritten so it calls `rspack` with `./rspack.config.ts` or `./.config/rspack/rspack.config.ts`, keeping its other commands and flags. Remove the CLI flags rspack does not support: `--progress`, `--color`, `--bail`, `--output-pathinfo`.
 
-9. For each file the codemod kept in `.config/webpack/`, copy what is still needed to a folder outside `.config/` (for example `build/`), port it to rspack, and update the imports. Do not delete the originals; list them so the user can delete them.
+10. For each file the codemod kept in `.config/webpack/`, copy what is still needed to a folder outside `.config/` (for example `build/`), port it to rspack, and update the imports. Do not delete the originals; list them so the user can delete them.
 
-10. Remove the webpack packages the codemod kept, once nothing imports them. Keep `webpack` itself if anything still imports it.
+11. Remove the webpack packages the codemod kept, once nothing imports them. Keep `webpack` itself if anything still imports it.
 
-11. Delete the root `webpack.config.*` and its helper files once everything in them is ported or commented with `TODO(rspack):`.
+12. Delete the root `webpack.config.*` and its helper files once everything in them is ported or commented with `TODO(rspack):`.
 
 ## Verify
 
 1. Install dependencies, then run the `typecheck` and `build` scripts. Both must pass, with any unportable code commented out.
-2. Check that `dist/` contains `module.js`, `plugin.json`, and every file that plugin code or `plugin.json` refers to by path at runtime. Imported images are hashed, so their names change.
+2. Check that `dist/` contains `module.js`, `plugin.json`, `module.css` if the entry code imports any CSS, and every file that plugin code or `plugin.json` refers to by path at runtime. Imported images are hashed, so their names change.
 3. Run the `dev` script briefly and check that it compiles and keeps watching.
 4. Fix only breakage caused by this migration.
 
 ## Report
 
-End with a list of every `TODO(rspack):` comment you added (file, line, one-line reason), every file the user should delete, any duplicate transpiler rule you removed or kept (step 5), every image reference you changed to an import or kept as a copy (step 6), and any `exportsPresence` errors you left for the user.
+End with a list of every `TODO(rspack):` comment you added (file, line, one-line reason), every file the user should delete, any duplicate transpiler rule you removed or kept (step 5), every image reference you changed to an import or kept as a copy (step 6), every global stylesheet (step 7), and any `exportsPresence` errors you left for the user.
 
 ## Out of scope
 

package/src/codemods/additions/scripts/rspack.test.ts

@@ -222,6 +222,7 @@ describe('rspack', () => {
       expect(result.doesFileExist('.config/rspack/liveReloadPlugin.ts')).toBe(false);
       expect(result.doesFileExist('.config/rspack/LicenseRspackPlugin.ts')).toBe(true);
       expect(result.doesFileExist('.config/rspack/DiagnosticsRspackPlugin.ts')).toBe(true);
+      expect(result.doesFileExist('.config/rspack/PluginCssRspackPlugin.ts')).toBe(true);
     });
   });
 
@@ -245,7 +246,7 @@ describe('rspack', () => {
       const result = addRspack(context);
       const externals = result.getFile('.config/bundler/externals.ts')!;
 
-      expect(externals).toContain('RspackOptions');
+      expect(externals).toContain('ExternalItem[]');
     });
 
     it('should re-render all bundler files', () => {
@@ -253,7 +254,7 @@ describe('rspack', () => {
 
       const result = addRspack(context);
 
-      expect(result.getFile('.config/bundler/externals.ts')).toContain('RspackOptions');
+      expect(result.getFile('.config/bundler/externals.ts')).toContain('ExternalItem[]');
       expect(result.getFile('.config/bundler/constants.ts')).toBe('// rendered template stub');
       expect(result.getFile('.config/bundler/copyFiles.ts')).toBe('// rendered template stub');
       expect(result.getFile('.config/bundler/utils.ts')).toBe('// rendered template stub');
@@ -314,7 +315,45 @@ describe('rspack', () => {
 
       // builtin:swc-loader runs with externalHelpers, so builds import @swc/helpers
       expect(pkg.devDependencies['@swc/helpers']).toBe(rspackDeps['@swc/helpers']);
-      expect(pkg.devDependencies['imports-loader']).toBe(rspackDeps['imports-loader']);
+      expect(pkg.devDependencies['sass-loader']).toBe(rspackDeps['sass-loader']);
+    });
+
+    it('should remove the css loaders that native css replaces', () => {
+      const context = createBaseContext();
+      const pkg = JSON.parse(context.getFile('package.json')!);
+      Object.assign(pkg.devDependencies, {
+        'css-loader': '^7.1.0',
+        'imports-loader': '^5.0.0',
+        'style-loader': '^4.0.0',
+      });
+      context.updateFile('package.json', JSON.stringify(pkg, null, 2));
+
+      const result = addRspack(context);
+      const updated = JSON.parse(result.getFile('package.json')!);
+
+      expect(updated.devDependencies['css-loader']).toBeUndefined();
+      expect(updated.devDependencies['imports-loader']).toBeUndefined();
+      expect(updated.devDependencies['style-loader']).toBeUndefined();
+    });
+
+    it('should keep css loaders a root build file still uses and report them', () => {
+      const context = createBaseContext();
+      const pkg = JSON.parse(context.getFile('package.json')!);
+      Object.assign(pkg.devDependencies, { 'css-loader': '^7.1.0', 'style-loader': '^4.0.0' });
+      context.updateFile('package.json', JSON.stringify(pkg, null, 2));
+      context.addFile(
+        'webpack.config.ts',
+        "export default { module: { rules: [{ use: ['style-loader', 'css-loader'] }] } };"
+      );
+
+      const result = addRspack(context);
+      const updated = JSON.parse(result.getFile('package.json')!);
+
+      expect(updated.devDependencies['css-loader']).toBe('^7.1.0');
+      expect(updated.devDependencies['style-loader']).toBe('^4.0.0');
+      const report = result.getMessage()?.body?.join('\n');
+      expect(report).toContain('css-loader');
+      expect(report).toContain('style-loader');
     });
 
     it('should not change the versions of base config packages the plugin already has', () => {
@@ -583,6 +622,51 @@ describe('rspack', () => {
     });
   });
 
+  describe('grafanaDependency', () => {
+    function runWithGrafanaDependency(dependencies?: Record<string, string>) {
+      const context = createBaseContext();
+      if (dependencies) {
+        context.addFile('src/plugin.json', JSON.stringify({ id: 'myorg-mypanel-panel', dependencies }, null, 2));
+      }
+      const result = addRspack(context);
+      const pluginJson = result.getFile('src/plugin.json');
+      return { result, dependencies: pluginJson ? JSON.parse(pluginJson).dependencies : undefined };
+    }
+
+    it('should raise grafanaDependency when it allows versions without react/jsx-runtime', () => {
+      const { result, dependencies } = runWithGrafanaDependency({ grafanaDependency: '>=10.0.0', plugins: '[]' });
+
+      expect(dependencies).toEqual({ grafanaDependency: '>=12.2.5', plugins: '[]' });
+      expect(result.getMessage()?.body?.join('\n')).toContain('>=12.2.5');
+    });
+
+    it('should raise grafanaDependency ranges that include backported versions', () => {
+      expect(runWithGrafanaDependency({ grafanaDependency: '>=11.6.11 <12 || >=12.2.5' }).dependencies).toEqual({
+        grafanaDependency: '>=12.2.5',
+      });
+    });
+
+    it('should keep grafanaDependency when it already requires a newer Grafana', () => {
+      expect(runWithGrafanaDependency({ grafanaDependency: '>=13.2.0' }).dependencies).toEqual({
+        grafanaDependency: '>=13.2.0',
+      });
+      expect(runWithGrafanaDependency({ grafanaDependency: '>=12.2.5' }).dependencies).toEqual({
+        grafanaDependency: '>=12.2.5',
+      });
+    });
+
+    it('should not fail when the plugin has no src/plugin.json', () => {
+      expect(runWithGrafanaDependency().dependencies).toBeUndefined();
+    });
+
+    it('should be idempotent', async () => {
+      const context = createBaseContext();
+      context.addFile('src/plugin.json', JSON.stringify({ dependencies: { grafanaDependency: '>=10.0.0' } }, null, 2));
+
+      await expect(addRspack).toBeIdempotent(context);
+    });
+  });
+
   describe('npm lockfile', () => {
     function createLockfile(rspackCoreVersion: string) {
       return JSON.stringify(

package/src/codemods/additions/scripts/rspack.ts

@@ -24,6 +24,7 @@ const RSPACK_CONFIG_FILES = [
   '.config/rspack/LiveReloadRspackPlugin.ts',
   '.config/rspack/LicenseRspackPlugin.ts',
   '.config/rspack/DiagnosticsRspackPlugin.ts',
+  '.config/rspack/PluginCssRspackPlugin.ts',
 ];
 
 // files the rspack template used to ship under another name. removed so they do not linger
@@ -80,6 +81,7 @@ export default function rspack(context: Context): Context {
 
   followUps.push(...addRootRspackConfigStub(context));
   followUps.push(...updatePackageJson(context));
+  followUps.push(...raiseGrafanaDependency(context));
   followUps.push(...deleteWebpackTemplateFiles(context));
   reportFollowUps(context, followUps);
 
@@ -232,6 +234,34 @@ function raiseNodeEngine(context: Context): void {
   context.updateFile('package.json', JSON.stringify({ ...packageJson, engines }, null, 2));
 }
 
+// the base config externalizes react/jsx-runtime, which Grafana provides from 12.2.5
+const MIN_GRAFANA_VERSION = '12.2.5';
+
+function raiseGrafanaDependency(context: Context): string[] {
+  const pluginJsonPath = 'src/plugin.json';
+  if (!context.doesFileExist(pluginJsonPath)) {
+    return [];
+  }
+
+  const pluginJson = readJsonFile<{ dependencies?: Record<string, unknown> }>(context, pluginJsonPath);
+  const grafanaRange = pluginJson.dependencies?.grafanaDependency;
+  if (typeof grafanaRange !== 'string' || !validRange(grafanaRange)) {
+    return [];
+  }
+
+  const lowestAllowedVersion = minVersion(grafanaRange);
+  if (!lowestAllowedVersion || !lt(lowestAllowedVersion, MIN_GRAFANA_VERSION)) {
+    return [];
+  }
+
+  const grafanaDependency = `>=${MIN_GRAFANA_VERSION}`;
+  const dependencies = { ...pluginJson.dependencies, grafanaDependency };
+  context.updateFile(pluginJsonPath, JSON.stringify({ ...pluginJson, dependencies }, null, 2));
+  return [
+    `Raised grafanaDependency in src/plugin.json from ${grafanaRange} to ${grafanaDependency}. Earlier versions of Grafana do not provide react/jsx-runtime, which the rspack config loads from Grafana.`,
+  ];
+}
+
 // npm refuses to move @rspack/cli and @rspack/core from 1 to 2 in one install while the lockfile
 // still pins the old versions (ERESOLVE). dropping the locked @rspack packages lets npm resolve
 // them again from package.json. pnpm and yarn upgrade them without help
@@ -310,7 +340,7 @@ export const RSPACK_DEV_DEPENDENCIES = [
   'rspack-merge',
   'rspack-plugin-virtual-module',
   'ts-checker-rspack-plugin',
-  // style-loader and imports-loader still need webpack, and diagnostics-webpack-plugin peers on webpack ^5.106
+  // diagnostics-webpack-plugin peers on webpack ^5.106
   'webpack',
   'ws',
 ];
@@ -318,8 +348,11 @@ export const RSPACK_DEV_DEPENDENCIES = [
 // packages only the webpack base config uses. removed unless a root build file still imports them
 export const WEBPACK_ONLY_DEV_DEPENDENCIES = [
   'copy-webpack-plugin',
+  'css-loader',
   'eslint-webpack-plugin',
   'fork-ts-checker-webpack-plugin',
+  'imports-loader',
+  'style-loader',
   'swc-loader',
   'terser-webpack-plugin',
   'webpack-cli',
@@ -331,15 +364,7 @@ export const WEBPACK_ONLY_DEV_DEPENDENCIES = [
 // packages the rendered .config/rspack and .config/bundler files load at build time that every
 // scaffold gets, so older plugins may have removed some of them. added only when missing.
 // @swc/helpers is needed because builtin:swc-loader runs with externalHelpers, which webpack did not
-export const BASE_CONFIG_DEV_DEPENDENCIES = [
-  '@swc/helpers',
-  'css-loader',
-  'imports-loader',
-  'replace-in-file-webpack-plugin',
-  'sass',
-  'sass-loader',
-  'style-loader',
-];
+export const BASE_CONFIG_DEV_DEPENDENCIES = ['@swc/helpers', 'replace-in-file-webpack-plugin', 'sass', 'sass-loader'];
 
 // the lists above say which packages the addition manages. their versions come from the package.json
 // template, so they always match the .config files rendered from that same template. the template is

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

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

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

@@ -9,6 +9,7 @@ import {
   BannerPlugin,
   Compilation,
   CopyRspackPlugin,
+  LightningCssMinimizerRspackPlugin,
   SubresourceIntegrityPlugin,
   SwcJsMinimizerRspackPlugin,
   type Configuration,
@@ -22,6 +23,7 @@ import RspackLiveReloadPlugin from './LiveReloadRspackPlugin.ts';
 import { BuildModeRspackPlugin } from './BuildModeRspackPlugin.ts';
 import { LicenseRspackPlugin } from './LicenseRspackPlugin.ts';
 import DiagnosticsRspackPlugin from './DiagnosticsRspackPlugin.ts';
+import { PluginCssRspackPlugin } from './PluginCssRspackPlugin.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';
@@ -52,9 +54,15 @@ const config = async (env: Env): Promise<Configuration> => {
 
     devtool: env.production ? 'source-map' : 'eval-source-map',
 
-    entry: await getEntries(),
+    // grafana-public-path sets the public path first. grafana-plugin-css adds ./module.css to the define() dependencies
+    entry: Object.fromEntries(
+      Object.entries(await getEntries()).map(([name, entryPath]) => [
+        name,
+        ['grafana-public-path', 'grafana-plugin-css', entryPath],
+      ])
+    ),
 
-    externals,
+    externals: [...externals, { 'grafana-plugin-css': './module.css' }],
 
     // Support WebAssembly according to latest spec - makes WebAssembly module async
     experiments: {
@@ -64,19 +72,15 @@ const config = async (env: Env): Promise<Configuration> => {
     mode: env.production ? 'production' : 'development',
 
     module: {
+      parser: {
+        // keeps default imports of CSS modules working: `import styles from './x.module.css'`
+        'css/auto': { namedExports: false },
+      },
+      generator: {
+        // class names of CSS modules start with the plugin id
+        'css/auto': { localIdentName: '[uniqueName]-[local]-[hash:6]' },
+      },
       rules: [
-        // This must come first in the rules array otherwise it breaks sourcemaps.
-        {
-          test: /src\/(?:.*\/)?module\.tsx?$/,
-          use: [
-            {
-              loader: 'imports-loader',
-              options: {
-                imports: `side-effects grafana-public-path`,
-              },
-            },
-          ],
-        },
         {
           exclude: /(node_modules)/,
           test: /\.[tj]sx?$/,
@@ -103,11 +107,12 @@ const config = async (env: Env): Promise<Configuration> => {
         },
         {
           test: /\.css$/,
-          use: ['style-loader', 'css-loader'],
+          type: 'css/auto',
         },
         {
           test: /\.s[ac]ss$/,
-          use: ['style-loader', 'css-loader', 'sass-loader'],
+          use: ['sass-loader'],
+          type: 'css/auto',
         },
         {
           test: /\.(png|jpe?g|gif|svg)$/,
@@ -128,6 +133,18 @@ const config = async (env: Env): Promise<Configuration> => {
 
     optimization: {
       minimize: Boolean(env.production),
+      splitChunks: {
+        cacheGroups: {
+          // CSS used by more than one lazy chunk goes into one shared file instead of a copy per chunk
+          sharedCss: {
+            type: /^css/,
+            chunks: 'async',
+            minChunks: 2,
+            minSize: 0,
+            priority: 10,
+          },
+        },
+      },
       minimizer: [
         new SwcJsMinimizerRspackPlugin({
           extractComments: { banner: false },
@@ -136,6 +153,7 @@ const config = async (env: Env): Promise<Configuration> => {
             compress: { pure_funcs: ['console.log', 'console.info'] },
           },
         }),
+        new LightningCssMinimizerRspackPlugin(),
       ],
     },
 
@@ -145,6 +163,8 @@ const config = async (env: Env): Promise<Configuration> => {
       },
       filename: '[name].js',
       chunkFilename: env.production ? '[name].js?_cache=[contenthash]' : '[name].js',
+      cssFilename: '[name].css',
+      cssChunkFilename: env.production ? '[name].css?_cache=[contenthash]' : '[name].css',
       library: {
         type: 'amd',
       },
@@ -157,6 +177,7 @@ const config = async (env: Env): Promise<Configuration> => {
     plugins: [
       new BuildModeRspackPlugin(),
       new LicenseRspackPlugin(),
+      new PluginCssRspackPlugin({ pluginId, publicPath: `public/plugins/${pluginId}/` }),
       virtualPublicPath,
       // Insert create plugin version information into the bundle
       new BannerPlugin({
@@ -166,6 +187,7 @@ const config = async (env: Env): Promise<Configuration> => {
         ].join('\n'),
         raw: true,
         entryOnly: true,
+        test: /\.js$/,
         // 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,
       }),

package/templates/common/_package.json

@@ -36,8 +36,8 @@
     "@types/ws": "^8.18.1",{{/if}}
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",{{#unless useRspack}}
-    "copy-webpack-plugin": "^14.0.0",{{/unless}}
-    "css-loader": "^7.1.0",
+    "copy-webpack-plugin": "^14.0.0",
+    "css-loader": "^7.1.0",{{/unless}}
     "diagnostics-webpack-plugin": "^1.0.1",
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.0",
@@ -45,8 +45,8 @@
     "eslint-plugin-react": "^7.37.0",
     "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",
+    "identity-obj-proxy": "^3.0.0",{{#unless useRspack}}
+    "imports-loader": "^5.0.0",{{/unless}}
     "intersection-observer": "^0.12.2",
     "jest": "^30.5.0",
     "jest-canvas-mock": "^2.5.2",
@@ -57,8 +57,8 @@
     "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 useRspack}}
+    "semver": "^7.7.0",{{#unless useRspack}}
+    "style-loader": "^4.0.0",
     "swc-loader": "^0.2.0",
     "terser-webpack-plugin": "^5.3.0",{{/unless}}
     "ts-node": "^10.9.0",{{#if useRspack}}