@lark-apaas/fullstack-rspack-preset 0.1.2-alpha.1 → 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 (4) hide show
  1. package/README.md +318 -0
  2. package/lib/index.d.ts +37 -2
  3. package/lib/index.js +110 -3
  4. package/package.json +4 -2
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.d.ts CHANGED
@@ -1,2 +1,37 @@
1
- export { createRecommendRspackConfig } from './preset';
2
- export type { CreateRecommendRspackConfigOptions } from './preset';
1
+ import type { Configuration } from '@rspack/core';
2
+ /**
3
+ * 创建 Fullstack Rspack 配置（简化版）
4
+ *
5
+ * 自动从环境变量读取配置，用户只需提供覆盖配置
6
+ *
7
+ * @param overrides - 用户自定义的 Rspack 配置，会与默认配置深度合并
8
+ * @returns 完整的 Rspack 配置对象
9
+ *
10
+ * @example
11
+ * ```javascript
12
+ * const { createFullstackRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
13
+ *
14
+ * module.exports = createFullstackRspackConfig({
15
+ * entry: {
16
+ * main: './client/src/index.tsx',
17
+ * },
18
+ * resolve: {
19
+ * alias: {
20
+ * '@': path.resolve(__dirname, 'client/src'),
21
+ * },
22
+ * },
23
+ * });
24
+ * ```
25
+ *
26
+ * 支持的环境变量：
27
+ * - NODE_ENV: development | production (默认: development)
28
+ * - ENABLE_REACT_REFRESH: true | false (默认: false)
29
+ * - ENABLE_INSPECTOR: true | false (默认: false)
30
+ * - NEED_ROUTES: true | false (默认: true)
31
+ * - CLIENT_BASE_PATH: 客户端基础路径 (默认: /)
32
+ * - ASSETS_CDN_PATH: 生产环境 CDN 路径 (默认: /)
33
+ * - SERVER_PORT: 服务器端口 (默认: 3000)
34
+ * - CLIENT_DEV_PORT: 客户端开发端口 (默认: 8080)
35
+ */
36
+ export declare function createFullstackRspackConfig(overrides?: Partial<Configuration>): Configuration;
37
+ export default createFullstackRspackConfig;
package/lib/index.js CHANGED
@@ -1,5 +1,112 @@
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
+ var __importDefault = (this && this.__importDefault) || function (mod) {
36
+ return (mod && mod.__esModule) ? mod : { "default": mod };
37
+ };
2
38
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.createRecommendRspackConfig = void 0;
4
- var preset_1 = require("./preset");
5
- Object.defineProperty(exports, "createRecommendRspackConfig", { enumerable: true, get: function () { return preset_1.createRecommendRspackConfig; } });
39
+ exports.createFullstackRspackConfig = createFullstackRspackConfig;
40
+ const webpack_merge_1 = require("webpack-merge");
41
+ const devtool_kits_1 = require("@lark-apaas/devtool-kits");
42
+ const path_1 = __importDefault(require("path"));
43
+ const preset_1 = require("./preset");
44
+ /**
45
+ * 创建 Fullstack Rspack 配置（简化版）
46
+ *
47
+ * 自动从环境变量读取配置，用户只需提供覆盖配置
48
+ *
49
+ * @param overrides - 用户自定义的 Rspack 配置，会与默认配置深度合并
50
+ * @returns 完整的 Rspack 配置对象
51
+ *
52
+ * @example
53
+ * ```javascript
54
+ * const { createFullstackRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
55
+ *
56
+ * module.exports = createFullstackRspackConfig({
57
+ * entry: {
58
+ * main: './client/src/index.tsx',
59
+ * },
60
+ * resolve: {
61
+ * alias: {
62
+ * '@': path.resolve(__dirname, 'client/src'),
63
+ * },
64
+ * },
65
+ * });
66
+ * ```
67
+ *
68
+ * 支持的环境变量：
69
+ * - NODE_ENV: development | production (默认: development)
70
+ * - ENABLE_REACT_REFRESH: true | false (默认: false)
71
+ * - ENABLE_INSPECTOR: true | false (默认: false)
72
+ * - NEED_ROUTES: true | false (默认: true)
73
+ * - CLIENT_BASE_PATH: 客户端基础路径 (默认: /)
74
+ * - ASSETS_CDN_PATH: 生产环境 CDN 路径 (默认: /)
75
+ * - SERVER_PORT: 服务器端口 (默认: 3000)
76
+ * - CLIENT_DEV_PORT: 客户端开发端口 (默认: 8080)
77
+ */
78
+ function createFullstackRspackConfig(overrides = {}) {
79
+ // 1. 自动加载 .env 文件
80
+ try {
81
+ Promise.resolve().then(() => __importStar(require('dotenv'))).then((dotenv) => dotenv.config({
82
+ path: path_1.default.resolve(process.cwd(), '.env'),
83
+ }));
84
+ }
85
+ catch (e) {
86
+ // dotenv 是可选依赖，如果没有安装也不影响使用
87
+ }
88
+ // 2. 从环境变量读取配置
89
+ const isDev = process.env.NODE_ENV !== 'production';
90
+ const enableReactRefresh = process.env.ENABLE_REACT_REFRESH === 'true';
91
+ // enableInspector 目前在 preset 内部由 isDev 控制，保留环境变量以备后续扩展
92
+ // const enableInspector = process.env.ENABLE_INSPECTOR === 'true';
93
+ const needRoutes = process.env.NEED_ROUTES !== 'false'; // 默认 true
94
+ // 3. 处理路径配置
95
+ const clientBasePath = (0, devtool_kits_1.normalizeBasePath)(process.env.CLIENT_BASE_PATH || '/');
96
+ const publicPath = isDev
97
+ ? (process.env.CLIENT_BASE_PATH || '/')
98
+ : (process.env.ASSETS_CDN_PATH || '/');
99
+ // 4. 调用原有的 preset 函数生成基础配置
100
+ // 注意：enableInspector 目前在 preset 中由 isDev 控制，暂不暴露为独立参数
101
+ const baseConfig = (0, preset_1.createRecommendRspackConfig)({
102
+ isDev,
103
+ enableReactRefresh,
104
+ needRoutes,
105
+ clientBasePath,
106
+ publicPath,
107
+ });
108
+ // 5. 深度合并用户配置
109
+ return (0, webpack_merge_1.merge)(baseConfig, overrides);
110
+ }
111
+ // 默认导出简化版 API
112
+ 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.1",
3
+ "version": "0.1.2-alpha.3",
4
4
  "files": [
5
5
  "lib"
6
6
  ],
@@ -30,10 +30,12 @@
30
30
  "@lark-apaas/miaoda-inspector-jsx-runtime": "^1.0.0",
31
31
  "@rspack/plugin-react-refresh": "^1.5.1",
32
32
  "clsx": "^2.1.1",
33
+ "dotenv": "^16.4.5",
33
34
  "echarts": "^6.0.0",
34
35
  "postcss-import": "^16.1.1",
35
36
  "react-refresh": "^0.17.0",
36
- "tailwind-merge": "^2.5.5"
37
+ "tailwind-merge": "^2.5.5",
38
+ "webpack-merge": "^6.0.1"
37
39
  },
38
40
  "devDependencies": {
39
41
  "@lark-apaas/devtool-kits": "^1.0.0",