From 3b238f9d59c2622dfd656bac4906190ba4665e85 Mon Sep 17 00:00:00 2001
From: Viorel Cojocaru <vio@beanon.com>
Date: Sat, 20 Jul 2024 18:55:22 +0200
Subject: [PATCH] doc(webpack-plugin): How to exclude virtual modules

---
 packages/webpack-plugin/README.md | 33 +++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/packages/webpack-plugin/README.md b/packages/webpack-plugin/README.md
index c43d63a548..df046dc8a1 100644
--- a/packages/webpack-plugin/README.md
+++ b/packages/webpack-plugin/README.md
@@ -76,19 +76,44 @@ module.exports = {
 - `stats` - [Webpack stats](https://webpack.js.org/configuration/stats) options
   default:
   ```js
-  {
+  // webpack.config.js
+  module.exports = {
+    // ...
     stats: {
       assets: true,
       chunks: true,
       modules: true,
       builtAt: true,
-      hash: true
-    }
-  }
+      hash: true,
+    },
+  };
   ```
 
 [How to configure webpack for better debugging and monitoring](https://relative-ci.com/documentation/guides/webpack-config)
 
+#### How to exclude virtual modules
+
+Some plugins use virtual modules as an intermediary step when generating JS modules. For example, [vanilla-extract](https://github.com/vanilla-extract-css/vanilla-extract) creates a virtual module for every `.css.js`/`css.ts` file based on the loader module path and the filename/source as query parameters:
+
+```
+./node_modules/@vanilla-extract/webpack-plugin/vanilla.virtual.css?%7B%22fileName%22%3A%22src%2Fcomponents%2Fcomponent%2Fcomponent.css.ts.vanilla.css%22%2C%22source%22%3A%22...%22%7D
+```
+
+Inlining the encoded source and the filename causes an increase in the size of the output stats and adds unnecessary entries to the stats. To ignore vanilla-extract virtual modules from the stats and from the bundle analysis report, use [`excludeModules`](https://webpack.js.org/configuration/stats/#statsexcludemodules) option:
+
+
+```js
+// webpack.config.js
+module.exports = {
+  // ...
+  stats: {
+    excludeModules: [
+      /@vanilla-extract\/webpack-plugin\/vanilla-virtual\.css/,
+    ],
+  },
+};
+```
+
 ### Use with create-react-app
 
 You will need to customize the default webpack config. That can be done by using [react-app-rewired](https://github.com/timarney/react-app-rewired) which is one of create-react-app's custom config solutions. You will also need [customize-cra](https://github.com/arackaf/customize-cra).