docs: add preact refresh guide (#6848)

* docs: add preact refresh * Update website/docs/zh/guide/tech/preact.mdx Co-authored-by: neverland <[email protected]> --------- Co-authored-by: neverland <[email protected]>
web-infra-dev · Jun 18, 2024 · b593043 · b593043
1 parent a99a256
commit b593043
Show file tree

Hide file tree

Showing 4 changed files with 244 additions and 0 deletions.
diff --git a/website/docs/en/guide/tech/_meta.json b/website/docs/en/guide/tech/_meta.json
@@ -4,6 +4,7 @@
   "json",
   "nodejs",
   "react",
+  "preact",
   "vue",
   "solid",
   "svelte",

diff --git a/website/docs/en/guide/tech/preact.mdx b/website/docs/en/guide/tech/preact.mdx
@@ -0,0 +1,121 @@
+import { PackageManagerTabs } from '@theme';
+import { ApiMeta, Stability } from '@components/ApiMeta.tsx';
+
+# Preact
+
+## How to Use
+
+You can refer to the current document to manually add configurations for Preact.
+
+## Configure JSX/TSX
+
+Rspack leverages SWC transformer for JSX/TSX.
+
+Add `builtin:swc-loader` loader to support `jsx` and `tsx`:
+
+```js title=rspack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.jsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            jsc: {
+              parser: {
+                syntax: 'ecmascript',
+                jsx: true,
+              },
+            },
+          },
+        },
+        type: 'javascript/auto',
+      },
+      {
+        test: /\.tsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            jsc: {
+              parser: {
+                syntax: 'typescript',
+                tsx: true,
+              },
+            },
+          },
+        },
+        type: 'javascript/auto',
+      },
+    ],
+  },
+};
+```
+
+Refer to [Builtin swc-loader](guide/features/builtin-swc-loader) for detailed configurations.
+
+Refer to [examples/preact](https://github.com/rspack-contrib/rspack-examples/blob/main/rspack/preact/rspack.config.js) for the full example.
+
+## Preact Refresh
+
+<ApiMeta addedVersion={'0.7.3'} />
+
+To enable Preact Refresh, the following steps are required:
+
+- Add the `@rspack/plugin-preact-refresh` plugin to inject runtime code
+- Add the loader for code transformation
+
+### @rspack/plugin-preact-refresh
+
+First you need to install the dependencies:
+
+<PackageManagerTabs command="add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D" />
+
+The enabling of the [Preact Refresh](https://github.com/preactjs/prefresh) is divided into two parts: code injection and code transformation
+
+- Code injection: injects code that interacts with `@prefresh/core` and `@prefresh/utils`, which has been integrated in the [@rspack/plugin-preact-refresh](https://github.com/web-infra-dev/rspack/tree/main/packages/rspack-plugin-preact-refresh) plugin
+- Code transformation requires a loader
+  - Use `builtin:swc-loader`
+    - Enable `jsc.transform.react.refresh` to support common react transformation
+    - Enable `rspackExperiments.preact` to support the specific transformation of preact
+  - Use `babel-loader` and add official [babel plugin](https://github.com/preactjs/prefresh/tree/main/packages/babel) of prefresh.
+
+```js title=rspack.config.js
+const PreactRefreshPlugin = require('@rspack/plugin-preact-refresh');
+const isDev = process.env.NODE_ENV === 'development';
+
+module.exports = {
+  // ...
+  mode: isDev ? 'development' : 'production',
+  module: {
+    rules: [
+      {
+        test: /\.jsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            rspackExperiments: {
+              preact: {}, // enable preact specific transformation
+            },
+            jsc: {
+              parser: {
+                syntax: 'ecmascript',
+                jsx: true,
+              },
+              transform: {
+                react: {
+                  development: isDev,
+                  refresh: isDev, // enable common react transformation
+                },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+  plugins: [isDev && new PreactRefreshPlugin()].filter(Boolean),
+};
+```
+
+Refer to [examples/preact-refresh](https://github.com/rspack-contrib/rspack-examples/blob/main/rspack/preact-refresh/rspack.config.js) for the full example.
diff --git a/website/docs/zh/guide/tech/_meta.json b/website/docs/zh/guide/tech/_meta.json
@@ -4,6 +4,7 @@
   "json",
   "nodejs",
   "react",
+  "preact",
   "vue",
   "solid",
   "svelte",

diff --git a/website/docs/zh/guide/tech/preact.mdx b/website/docs/zh/guide/tech/preact.mdx
@@ -0,0 +1,121 @@
+import { PackageManagerTabs } from '@theme';
+import { ApiMeta, Stability } from '@components/ApiMeta.tsx';
+
+# Preact
+
+## 如何使用
+
+你可以参考当前文档，手动添加 Preact 相关的配置。
+
+## 配置 JSX/TSX
+
+Rspack 使用 SWC 转译器支持 JSX/TSX。
+
+添加 `builtin:swc-loader` 以支持 `jsx` 和 `tsx`:
+
+```js title=rspack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.jsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            jsc: {
+              parser: {
+                syntax: 'ecmascript',
+                jsx: true,
+              },
+            },
+          },
+        },
+        type: 'javascript/auto',
+      },
+      {
+        test: /\.tsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            jsc: {
+              parser: {
+                syntax: 'typescript',
+                tsx: true,
+              },
+            },
+          },
+        },
+        type: 'javascript/auto',
+      },
+    ],
+  },
+};
+```
+
+关于配置项的更多信息请参考 [内置 swc-loader](guide/features/builtin-swc-loader)。
+
+完整示例可参考：[examples/preact](https://github.com/rspack-contrib/rspack-examples/blob/main/rspack/preact/rspack.config.js)
+
+## Preact Refresh
+
+<ApiMeta addedVersion={'0.7.3'} />
+
+需要开启 Preact Refresh 需要如下步骤：
+
+- 添加 `@rspack/plugin-preact-refresh` 插件
+- 添加代码转换相关 loader
+
+### @rspack/plugin-preact-refresh
+
+首先需要安装相关依赖：
+
+<PackageManagerTabs command="add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D" />
+
+[Preact Refresh](https://github.com/preactjs/prefresh) 功能的开启主要分为两部分：代码注入和代码转换
+
+- 代码注入：指注入与 `@prefresh/core` 和 `@prefresh/utils` 交互的代码，都已集成在 [@rspack/plugin-preact-refresh](https://github.com/web-infra-dev/rspack/tree/main/packages/rspack-plugin-preact-refresh) 插件中，可通过该插件实现
+- 代码转换需要通过 loader 来完成：
+  - 使用 `builtin:swc-loader`
+    - 开启 `jsc.transform.react.refresh` 以支持通用的 react 转换
+    - 开启 `rspackExperiments.preact` 以支持 preact 特有的转换
+  - 使用 `babel-loader` 并接入 prefresh 官方[babel 插件](https://github.com/preactjs/prefresh/tree/main/packages/babel)。
+
+```js title=rspack.config.js
+const PreactRefreshPlugin = require('@rspack/plugin-preact-refresh');
+const isDev = process.env.NODE_ENV === 'development';
+
+module.exports = {
+  // ...
+  mode: isDev ? 'development' : 'production',
+  module: {
+    rules: [
+      {
+        test: /\.jsx$/,
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            rspackExperiments: {
+              preact: {}, // 开启 preact 特有转换
+            },
+            jsc: {
+              parser: {
+                syntax: 'ecmascript',
+                jsx: true,
+              },
+              transform: {
+                react: {
+                  development: isDev,
+                  refresh: isDev, // 开启 react 通用转换
+                },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+  plugins: [isDev && new PreactRefreshPlugin()].filter(Boolean),
+};
+```
+
+完整示例可参考：[examples/preact-refresh](https://github.com/rspack-contrib/rspack-examples/blob/main/rspack/preact-refresh/rspack.config.js)