docs: add how to preserve module variables (#1010)

Author: Timeless0911

website/docs/en/config/rsbuild/source.mdx

@@ -17,7 +17,7 @@ If [experimentalDecorators](https://www.typescriptlang.org/tsconfig/#experimenta
 
 ## source.define <RsbuildDocBadge path="/config/source/define" text="source.define" />
 
-Replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds.
+Replaces variables in your code with other values or expressions at compile time. This can be useful for injecting env variables and other information to the code during build time.
 
 ## source.entry <RsbuildDocBadge path="/config/source/entry" text="source.entry" />
 

website/docs/en/guide/faq/features.mdx

@@ -48,7 +48,7 @@ By default, Rslib uses SWC to remove comments. The corresponding SWC [jsc.minify
 }
 ```
 
-This will only preserve some legal comments and annotations. If you want to preserve all comments, you can refer to the following configuration
+This will only preserve some legal comments and annotations. If you want to preserve all comments, you can refer to the following configuration:
 
 ```ts title="rslib.config.ts"
 export default {
@@ -113,3 +113,30 @@ export default {
   },
 };
 ```
+
+## Miscellaneous
+
+### How to preserve module variables such as `__webpack_hash__` in the source code when generating outputs?
+
+Rslib based on Rspack will transform [module variables](https://rspack.dev/api/runtime-api/module-variables) like `__webpack_hash__`, `__webpack_nonce__`, `__webpack_public_path__`, etc. to runtime code containing `__webpack_require__` by default during build process. If you need to preserve these module variables in the outputs, you can configure [source.define](/config/rsbuild/source#sourcedefine) as follows:
+
+1. Replace the module variables that need to be preserved in the source code with a unique name, such as `__webpack_hash__` with `WEBPACK_HASH`, `__webpack_nonce__` with `WEBPACK_NONCE`, `__webpack_public_path__` with `WEBPACK_PUBLIC_PATH`, etc.
+
+```ts
+const isUpdateAvailable = () => lastCompilationHash !== __webpack_hash__; // [!code --]
+const isUpdateAvailable = () => lastCompilationHash !== WEBPACK_HASH; // [!code ++]
+```
+
+2. Add the module variables that need to be preserved in `source.define`. The key of the passed configuration object is the replaced variable name in the source code, and the value is the module variable that needs to be preserved in the outputs.
+
+```ts title="rslib.config.ts"
+export default defineConfig({
+  source: {
+    define: {
+      WEBPACK_HASH: '__webpack_hash__',
+      WEBPACK_NONCE: '__webpack_nonce__',
+      WEBPACK_PUBLIC_PATH: '__webpack_public_path__',
+    },
+  },
+});
+```

website/docs/zh/config/rsbuild/source.mdx

@@ -16,7 +16,7 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
 
 ## source.define <RsbuildDocBadge path="/config/source/define" text="source.define" />
 
-构建时将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发模式与生产模式等场景。
+构建时将代码中的变量替换成其它值或者表达式，可以用于在构建时向代码注入环境变量等信息。
 
 ## source.entry <RsbuildDocBadge path="/config/source/entry" text="source.entry" />
 

website/docs/zh/guide/faq/features.mdx

@@ -48,7 +48,7 @@ export default defineConfig({
 }
 ```
 
-这将仅保留部分 legal 注释及 annotations。如果你想保留所有注释，可以参考如下配置
+这将仅保留部分 legal 注释及 annotations。如果你想保留所有注释，可以参考如下配置：
 
 ```ts title="rslib.config.ts"
 export default {
@@ -113,3 +113,30 @@ export default {
   },
 };
 ```
+
+## 其他
+
+### 如何在生成产物时保留源码中的 `__webpack_hash__` 等模块变量？
+
+Rslib 底层使用的 Rspack，在构建时会默认将 `__webpack_hash__`、`__webpack_nonce__`、`__webpack_public_path__` 等 [模块变量](https://rspack.dev/zh/api/runtime-api/module-variables) 转换为包含 `__webpack_require__` 的运行时代码。如果你需要在产物中保留这些模块变量，可以通过配置 [source.define](/config/rsbuild/source#sourcedefine) 来实现，如下所示：
+
+1. 在源码中将需要保留的模块变量替换为一个特征名称，如 `__webpack_hash__` 替换为 `WEBPACK_HASH`，`__webpack_nonce__` 替换为 `WEBPACK_NONCE`，`__webpack_public_path__` 替换为 `WEBPACK_PUBLIC_PATH` 等。
+
+```ts
+const isUpdateAvailable = () => lastCompilationHash !== __webpack_hash__; // [!code --]
+const isUpdateAvailable = () => lastCompilationHash !== WEBPACK_HASH; // [!code ++]
+```
+
+2. 在 `source.define` 中添加需要保留的模块变量，传入的配置对象的键名是源码中替换后的变量名称，值是需要在产物中保留的模块变量。
+
+```ts title="rslib.config.ts"
+export default defineConfig({
+  source: {
+    define: {
+      WEBPACK_HASH: '__webpack_hash__',
+      WEBPACK_NONCE: '__webpack_nonce__',
+      WEBPACK_PUBLIC_PATH: '__webpack_public_path__',
+    },
+  },
+});
+```

website/rspress.config.ts

@@ -2,7 +2,10 @@ import path from 'node:path';
 import { pluginSass } from '@rsbuild/plugin-sass';
 import { pluginLlms } from '@rspress/plugin-llms';
 import { pluginRss } from '@rspress/plugin-rss';
-import { transformerNotationHighlight } from '@shikijs/transformers';
+import {
+  transformerNotationDiff,
+  transformerNotationHighlight,
+} from '@shikijs/transformers';
 import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';
 import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';
 import { pluginFontOpenSans } from 'rspress-plugin-font-open-sans';
@@ -53,7 +56,7 @@ export default defineConfig({
   markdown: {
     checkDeadLinks: true,
     shiki: {
-      transformers: [transformerNotationHighlight()],
+      transformers: [transformerNotationHighlight(), transformerNotationDiff()],
     },
   },
   search: {