@lark-apaas/fullstack-rspack-preset 0.1.2-alpha.2 → 0.1.2-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +318 -0
  2. package/lib/index.js +7 -1
  3. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,318 @@
1
+ # @lark-apaas/fullstack-rspack-preset
2
+
3
+ > 开箱即用的 Fullstack Rspack 配置预设
4
+
5
+ 提供开箱即用的 Rspack 配置，包含路由解析、性能监控、模块别名、HMR 等完整功能。
6
+
7
+ ## 特性
8
+
9
+ - ✅ **零配置** - 环境变量驱动，开箱即用
10
+ - ✅ **路由解析** - 自动解析 React Router 路由生成 routes.json
11
+ - ✅ **性能监控** - 集成 Slardar 性能监控
12
+ - ✅ **模块优化** - clsx + tailwind-merge、echarts 别名
13
+ - ✅ **HMR 监控** - 热更新时间统计
14
+ - ✅ **React Refresh** - 支持 React 快速刷新
15
+ - ✅ **TypeScript** - 完整的类型定义
16
+ - ✅ **向后兼容** - 同时支持新旧两种 API
17
+
18
+ ## 安装
19
+
20
+ ```bash
21
+ npm install @lark-apaas/fullstack-rspack-preset
22
+ # or
23
+ yarn add @lark-apaas/fullstack-rspack-preset
24
+ ```
25
+
26
+ ## 快速开始
27
+
28
+ ### 1. 简化版 API（推荐）
29
+
30
+ 只需提供必要的覆盖配置，其他都通过环境变量控制。
31
+
32
+ ```javascript
33
+ // rspack.config.js
34
+ const path = require('path');
35
+ const { createFullstackRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
36
+
37
+ module.exports = createFullstackRspackConfig({
38
+ entry: {
39
+ main: './client/src/index.tsx',
40
+ },
41
+ resolve: {
42
+ alias: {
43
+ '@': path.resolve(__dirname, 'client/src'),
44
+ },
45
+ },
46
+ });
47
+ ```
48
+
49
+ ### 2. 环境变量配置
50
+
51
+ 在项目根目录创建 `.env` 文件：
52
+
53
+ ```bash
54
+ # 环境模式
55
+ NODE_ENV=development
56
+
57
+ # 功能开关
58
+ ENABLE_REACT_REFRESH=true
59
+ ENABLE_INSPECTOR=false
60
+ NEED_ROUTES=true
61
+
62
+ # 路径配置
63
+ CLIENT_BASE_PATH=/
64
+ ASSETS_CDN_PATH=https://cdn.example.com
65
+
66
+ # 端口配置
67
+ SERVER_PORT=3000
68
+ CLIENT_DEV_PORT=8080
69
+ ```
70
+
71
+ ### 3. 运行
72
+
73
+ ```bash
74
+ # 开发模式
75
+ npx rspack serve --config rspack.config.js --env mode=development
76
+
77
+ # 生产构建
78
+ NODE_ENV=production npx rspack build --config rspack.config.js
79
+ ```
80
+
81
+ ## API 文档
82
+
83
+ ### createFullstackRspackConfig (简化版)
84
+
85
+ 自动从环境变量读取配置，用户只需提供覆盖配置。
86
+
87
+ ```typescript
88
+ function createFullstackRspackConfig(
89
+ overrides?: Partial<Configuration>
90
+ ): Configuration;
91
+ ```
92
+
93
+ **参数：**
94
+ - `overrides` - Rspack 配置对象，会与默认配置深度合并
95
+
96
+ **环境变量：**
97
+
98
+ | 环境变量 | 类型 | 默认值 | 说明 |
99
+ |---------|------|--------|------|
100
+ | `NODE_ENV` | `development \| production` | `development` | 环境模式 |
101
+ | `ENABLE_REACT_REFRESH` | `boolean` | `false` | 是否启用 React Refresh |
102
+ | `ENABLE_INSPECTOR` | `boolean` | `false` | 是否启用 Miaoda Inspector |
103
+ | `NEED_ROUTES` | `boolean` | `true` | 是否需要路由解析 |
104
+ | `CLIENT_BASE_PATH` | `string` | `/` | 客户端基础路径 |
105
+ | `ASSETS_CDN_PATH` | `string` | `/` | 生产环境 CDN 路径 |
106
+ | `SERVER_PORT` | `number` | `3000` | 服务器端口 |
107
+ | `CLIENT_DEV_PORT` | `number` | `8080` | 客户端开发端口 |
108
+
109
+ ### createRecommendRspackConfig (传统版)
110
+
111
+ 提供更细粒度的控制，需要手动处理环境变量。
112
+
113
+ ```typescript
114
+ function createRecommendRspackConfig(
115
+ options: CreateRecommendRspackConfigOptions
116
+ ): Configuration;
117
+
118
+ interface CreateRecommendRspackConfigOptions {
119
+ isDev?: boolean;
120
+ enableReactRefresh?: boolean;
121
+ needRoutes?: boolean;
122
+ clientBasePath?: string;
123
+ publicPath?: string;
124
+ }
125
+ ```
126
+
127
+ **示例：**
128
+
129
+ ```javascript
130
+ const { createRecommendRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
131
+ const { normalizeBasePath } = require('@lark-apaas/devtool-kits');
132
+
133
+ require('dotenv').config();
134
+
135
+ const isDev = process.env.NODE_ENV !== 'production';
136
+
137
+ module.exports = createRecommendRspackConfig({
138
+ isDev,
139
+ enableReactRefresh: true,
140
+ clientBasePath: normalizeBasePath(process.env.CLIENT_BASE_PATH || '/'),
141
+ publicPath: isDev ? '/' : 'https://cdn.example.com',
142
+ });
143
+ ```
144
+
145
+ ## 内置插件和功能
146
+
147
+ ### 1. RouteParserPlugin
148
+
149
+ 自动解析 React Router 路由，生成 `routes.json` 文件。
150
+
151
+ - **输入**：`./client/src/app.tsx`
152
+ - **输出**：`dist/client/routes.json`
153
+ - **控制**：`NEED_ROUTES` 环境变量
154
+
155
+ ### 2. SlardarPerformanceMonitorPlugin
156
+
157
+ 注入 Slardar 性能监控脚本到 HTML。
158
+
159
+ - **位置**：`<head>` 标签末尾
160
+ - **包含**：Slardar SDK + Performance 监控
161
+
162
+ ### 3. Module Alias
163
+
164
+ #### clsx 别名
165
+ 将 `clsx` 替换为增强版本，自动集成 `tailwind-merge`：
166
+
167
+ ```javascript
168
+ import { clsx } from 'clsx'; // 自动包含 twMerge 功能
169
+ ```
170
+
171
+ #### echarts 别名
172
+ 优化 echarts 导入路径。
173
+
174
+ ### 4. HMR Timing Monitor
175
+
176
+ 开发模式下自动监控热更新时间，通过 WebSocket 推送给客户端。
177
+
178
+ ### 5. 代理配置
179
+
180
+ 自动配置开发服务器代理：
181
+ - API 代理：`${CLIENT_BASE_PATH}/api` → `http://localhost:${SERVER_PORT}`
182
+ - HTML 代理：所有 HTML 请求 → `http://localhost:${SERVER_PORT}`
183
+
184
+ ## 项目结构要求
185
+
186
+ ```
187
+ your-project/
188
+ ├── .env # 环境变量配置
189
+ ├── rspack.config.js # Rspack 配置
190
+ ├── client/
191
+ │ ├── public/ # 静态资源
192
+ │ └── src/
193
+ │ ├── app.tsx # 路由定义（需包含 React Router）
194
+ │ └── index.tsx # 入口文件
195
+ ├── server/ # 服务端代码
196
+ └── dist/
197
+ └── client/ # 构建产物
198
+ ├── routes.json # 路由文件（自动生成）
199
+ └── ...
200
+ ```
201
+
202
+ ## 迁移指南
203
+
204
+ ### 从旧 API 迁移到新 API
205
+
206
+ **之前（15 行）：**
207
+
208
+ ```javascript
209
+ const { defineConfig } = require('@rspack/cli');
210
+ const { createRecommendRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
211
+ const { normalizeBasePath } = require('@lark-apaas/devtool-kits');
212
+ const { default: merge } = require('webpack-merge');
213
+
214
+ require('dotenv').config();
215
+
216
+ module.exports = defineConfig(({mode}) => {
217
+ const isDev = mode !== 'production';
218
+ const basePathWithoutTrailingSlash = normalizeBasePath(process.env.CLIENT_BASE_PATH || '/');
219
+ const publicPath = isDev ? '/' : process.env.ASSETS_CDN_PATH;
220
+
221
+ const baseConfig = createRecommendRspackConfig({
222
+ isDev,
223
+ clientBasePath: basePathWithoutTrailingSlash,
224
+ publicPath: publicPath,
225
+ });
226
+
227
+ return merge(baseConfig, {
228
+ entry: { main: './client/src/index.tsx' },
229
+ });
230
+ });
231
+ ```
232
+
233
+ **现在（8 行）：**
234
+
235
+ ```javascript
236
+ const path = require('path');
237
+ const { createFullstackRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
238
+
239
+ module.exports = createFullstackRspackConfig({
240
+ entry: {
241
+ main: './client/src/index.tsx',
242
+ },
243
+ resolve: {
244
+ alias: {
245
+ '@': path.resolve(__dirname, 'client/src'),
246
+ },
247
+ },
248
+ });
249
+ ```
250
+
251
+ **迁移步骤：**
252
+
253
+ 1. 修改导入：`createRecommendRspackConfig` → `createFullstackRspackConfig`
254
+ 2. 删除手动环境变量处理代码
255
+ 3. 删除 `defineConfig`、`normalizeBasePath`、`merge` 等导入
256
+ 4. 只保留覆盖配置（entry、resolve 等）
257
+ 5. 确保 `.env` 文件包含必要的环境变量
258
+
259
+ ## 常见问题
260
+
261
+ ### Q: 如何禁用某个功能？
262
+
263
+ 通过环境变量控制：
264
+
265
+ ```bash
266
+ # 禁用路由解析
267
+ NEED_ROUTES=false
268
+
269
+ # 禁用 React Refresh
270
+ ENABLE_REACT_REFRESH=false
271
+ ```
272
+
273
+ ### Q: 如何自定义 DefinePlugin 变量？
274
+
275
+ 直接在 `overrides` 中添加：
276
+
277
+ ```javascript
278
+ module.exports = createFullstackRspackConfig({
279
+ plugins: [
280
+ new rspack.DefinePlugin({
281
+ 'process.env.CUSTOM_VAR': JSON.stringify('custom-value'),
282
+ }),
283
+ ],
284
+ });
285
+ ```
286
+
287
+ ### Q: 如何使用生产环境 CDN？
288
+
289
+ 设置环境变量：
290
+
291
+ ```bash
292
+ NODE_ENV=production
293
+ ASSETS_CDN_PATH=https://cdn.example.com
294
+ ```
295
+
296
+ ### Q: 为什么 DefinePlugin 没有生效？
297
+
298
+ 检查：
299
+ 1. `.env` 文件是否存在
300
+ 2. 环境变量名是否正确
301
+ 3. `process.env.runtimeMode` 缺少 `JSON.stringify`（已知问题，待修复）
302
+
303
+ ## 版本历史
304
+
305
+ ### 0.1.2-alpha.2
306
+ - ✨ 新增 `createFullstackRspackConfig` 简化 API
307
+ - ✨ 自动加载 `.env` 环境变量
308
+ - ✨ 支持环境变量驱动配置
309
+ - 🐛 修复 `@rspack/core` 版本冲突
310
+ - 🐛 修复 Slardar 插件在 npm link 环境下的问题
311
+ - 📝 完善文档和示例
312
+
313
+ ### 0.1.0
314
+ - 🎉 初始版本
315
+
316
+ ## License
317
+
318
+ MIT
package/lib/index.js CHANGED
@@ -32,10 +32,14 @@ var __importStar = (this && this.__importStar) || (function () {
32
32
  return result;
33
33
  };
34
34
  })();
35
+ var __importDefault = (this && this.__importDefault) || function (mod) {
36
+ return (mod && mod.__esModule) ? mod : { "default": mod };
37
+ };
35
38
  Object.defineProperty(exports, "__esModule", { value: true });
36
39
  exports.createFullstackRspackConfig = createFullstackRspackConfig;
37
40
  const webpack_merge_1 = require("webpack-merge");
38
41
  const devtool_kits_1 = require("@lark-apaas/devtool-kits");
42
+ const path_1 = __importDefault(require("path"));
39
43
  const preset_1 = require("./preset");
40
44
  /**
41
45
  * 创建 Fullstack Rspack 配置（简化版）
@@ -74,7 +78,9 @@ const preset_1 = require("./preset");
74
78
  function createFullstackRspackConfig(overrides = {}) {
75
79
  // 1. 自动加载 .env 文件
76
80
  try {
77
- Promise.resolve().then(() => __importStar(require('dotenv'))).then((dotenv) => dotenv.config());
81
+ Promise.resolve().then(() => __importStar(require('dotenv'))).then((dotenv) => dotenv.config({
82
+ path: path_1.default.resolve(process.cwd(), '.env'),
83
+ }));
78
84
  }
79
85
  catch (e) {
80
86
  // dotenv 是可选依赖，如果没有安装也不影响使用
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lark-apaas/fullstack-rspack-preset",
3
- "version": "0.1.2-alpha.2",
3
+ "version": "0.1.2-alpha.3",
4
4
  "files": [
5
5
  "lib"
6
6
  ],