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

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