@taro-hmr-compile/preset 0.0.1-alpha.9 → 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+# @taro-hmr-compile/preset
+
+面向 Taro React + Webpack 5 微信小程序的按需编译与热更新预设，一次注册即可集成页面按需编译、增量补丁和 React Refresh。
+
+## ✨ 功能特性
+
+| 集成插件 | 功能 |
+| --- | --- |
+| [`@taro-hmr-compile/react-refresh/compiler`](../react-refresh/README.md) | 注入 React Refresh Babel 转换与 Webpack 运行时 |
+| [`@taro-hmr-compile/plugin-webpack`](../taro-plugin-webpack/README.md) | 页面按需编译、本地编译服务、模块与样式补丁 |
+
+预设按上述顺序注册插件，仅在 Taro `--watch` 模式下启用。
+
+## 📦 安装
+
+```bash
+pnpm add -D @taro-hmr-compile/preset
+```
+
+## ⚙️ 配置
+
+将以下选项合并到现有 `config/index.ts`：
+
+```ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig<'webpack5'>({
+  framework: 'react',
+  mini: {
+    debugReact: true,
+  },
+  compiler: {
+    type: 'webpack5',
+    prebundle: { enable: false },
+  },
+  presets: [
+    ['@taro-hmr-compile/preset', {
+      host: '127.0.0.1',
+      port: 8080,
+      debug: true,
+      patchHistoryLimit: 20,
+      lazyCompileExclude: ['pages/index/index'],
+    }],
+  ],
+})
+```
+
+需要开启 `mini.debugReact: true`，使用 React 开发版本以支持 React Refresh。建议沿用仓库示例关闭预打包；预设自动注入 Babel 插件，无需手动添加 `react-refresh/babel`。
+
+在 `project.config.json` 中合并以下设置，以允许本地 HTTP 编译请求并开启开发者工具热重载：
+
+```json
+{
+  "setting": {
+    "urlCheck": false,
+    "compileHotReLoad": true
+  }
+}
+```
+
+## 🚀 使用
+
+```bash
+pnpm exec taro build --type weapp --watch
+```
+
+用微信开发者工具打开项目，并让 `miniprogramRoot` 指向构建目录。未编译页面首次进入时显示占位界面，随后请求本地编译服务并通过补丁加载真实内容。`lazyCompileExclude` 中的页面直接参与首次编译。
+
+常规生产构建不带 `--watch`，插件不会启用，无需移除预设。
+
+## 📋 配置选项
+
+导出的 `TaroHmrCompilePresetOptions` 为 `Partial<WebpackHmrCompileOpt>`，全部选项直接传给 Webpack 插件。
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `host` | `string` | `'127.0.0.1'` | 服务监听地址，同时用于页面编译请求 URL |
+| `port` | `number` | `8080` | 首选端口，被占用时自动寻找可用端口 |
+| `patchHistoryLimit` | `number` | `20` | 更新补丁记录数上限；超出后合并最早的记录，最小按 `1` 处理 |
+| `debug` | `boolean \| string` | `false` | `true` 开启 `taro-hmr-compile:*`，字符串指定 debug 命名空间 |
+| `lazyCompileExclude` | `string[]` | `[]` | 首次构建直接编译的页面路径，不影响后续热更新 |
+
+排除路径相对于 `sourceRoot`，不含扩展名，支持开头 `/`；末尾 `/` 表示目录前缀匹配。例如 `pages/index/index` 匹配单页，`pages/dashboard/` 匹配目录下页面。默认排除列表为空，首屏也会先显示占位组件。
+
+## ⚠️ 注意事项
+
+- 当前为 Alpha 版本，仓库示例采用 Taro 4.2.1、React 18 和 Webpack 5；其他版本组合需自行验证。
+- 面向 React 微信小程序开发。其他平台 watch 构建建议按 `process.env.TARO_ENV === 'weapp'` 条件注册。
+- 不要同时使用本预设和手动注册其内部插件，以免重复注入。
+- `host` 也是客户端访问地址，不能将 `0.0.0.0` 当作客户端可访问地址；真机网络及热更新行为需单独验证。
+- 修改配置后重启 watch 进程。状态保留受 React Refresh 边界和 Hook 签名限制，并非所有修改都能保留状态。
+
+完整使用流程和排查方法见[根 README](../../README.md)，示例配置见 [`config/index.ts`](../../examples/taro-react-webpack/config/index.ts)。
+
+## 📄 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taro-hmr-compile/preset",
-  "version": "0.0.1-alpha.9",
+  "version": "0.0.1",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,8 +23,8 @@
     "typescript": "^5.8.2"
   },
   "dependencies": {
-    "@taro-hmr-compile/plugin-webpack": "0.0.1-alpha.9",
-    "@taro-hmr-compile/react-refresh": "0.0.1-alpha.9"
+    "@taro-hmr-compile/plugin-webpack": "0.0.1",
+    "@taro-hmr-compile/react-refresh": "0.0.1"
   },
   "scripts": {
     "build": "tsc"