@lark-apaas/fullstack-rspack-preset 0.1.2-alpha.6 → 1.0.0

package/README.md

@@ -2,32 +2,57 @@
 
 > 开箱即用的 Fullstack Rspack 配置预设
 
-提供开箱即用的 Rspack 配置，包含路由解析、性能监控、模块别名、HMR 等完整功能。
+提供开箱即用的 Rspack 配置，包含 TypeScript、React、路由解析、HMR 等完整功能。
 
 ## 特性
 
 - ✅ **零配置** - 环境变量驱动，开箱即用
-- ✅ **路由解析** - 自动解析 React Router 路由生成 routes.json
-- ✅ **性能监控** - 集成 Slardar 性能监控
-- ✅ **模块优化** - clsx + tailwind-merge、echarts 别名
-- ✅ **HMR 监控** - 热更新时间统计
+- ✅ **两种使用方式** - 支持 extends 继承和 defineConfig 函数
+- ✅ **TypeScript** - 完整的类型定义和 TSX 支持
 - ✅ **React Refresh** - 支持 React 快速刷新
-- ✅ **TypeScript** - 完整的类型定义
-- ✅ **向后兼容** - 同时支持新旧两种 API
+- ✅ **路由解析** - 自动解析 React Router 路由
+- ✅ **模块优化** - clsx + tailwind-merge、echarts 别名
+- ✅ **开发体验** - HMR 监控、代理配置
 
 ## 安装
 
 ```bash
 npm install @lark-apaas/fullstack-rspack-preset
-# or
-yarn add @lark-apaas/fullstack-rspack-preset
 ```
 
-## 快速开始
+## 使用方式
+
+### 方式 1: extends（推荐给简单场景）
+
+类似 ESLint、TypeScript 的配置继承方式：
+
+```javascript
+// rspack.config.js
+const path = require('path');
+
+module.exports = {
+  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
+  entry: {
+    main: './client/src/index.tsx',
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'client/src'),
+    },
+  },
+};
+```
+
+**特点：**
+- ✅ 简洁明了（4 行配置）
+- ✅ 符合 webpack/rspack 惯例
+- ✅ 配置自动深度合并
+
+---
 
-### 1. 简化版 API（推荐）
+### 方式 2: defineConfig（推荐给复杂场景）
 
-只需提供必要的覆盖配置，其他都通过环境变量控制。
+函数式调用，更灵活：
 
 ```javascript
 // rspack.config.js
@@ -46,7 +71,14 @@ module.exports = defineConfig({
 });
 ```
 
-### 2. 环境变量配置
+**特点：**
+- ✅ TypeScript 类型推断更好
+- ✅ 可以动态计算配置
+- ✅ 更灵活的配置方式
+
+---
+
+## 环境变量配置
 
 在项目根目录创建 `.env` 文件：
 
@@ -56,7 +88,6 @@ NODE_ENV=development
 
 # 功能开关
 ENABLE_REACT_REFRESH=true
-ENABLE_INSPECTOR=false
 NEED_ROUTES=true
 
 # 路径配置
@@ -68,231 +99,135 @@ SERVER_PORT=3000
 CLIENT_DEV_PORT=8080
 ```
 
-### 3. 运行
-
-```bash
-# 开发模式
-npx rspack serve --config rspack.config.js --env mode=development
-
-# 生产构建
-NODE_ENV=production npx rspack build --config rspack.config.js
-```
-
-## API 文档
-
-### createFullstackRspackConfig / defineConfig（推荐）
-
-自动从环境变量读取配置，用户只需提供覆盖配置。
-
-```typescript
-function defineConfig(
-  overrides?: Partial<Configuration>
-): Configuration;
-
-// 别名：createFullstackRspackConfig（向后兼容）
-function createFullstackRspackConfig(
-  overrides?: Partial<Configuration>
-): Configuration;
-```
-
-**参数：**
-- `overrides` - Rspack 配置对象，会与默认配置深度合并
-
-**环境变量：**
-
-| 环境变量 | 类型 | 默认值 | 说明 |
-|---------|------|--------|------|
-| `NODE_ENV` | `development \| production` | `development` | 环境模式 |
-| `ENABLE_REACT_REFRESH` | `boolean` | `false` | 是否启用 React Refresh |
-| `ENABLE_INSPECTOR` | `boolean` | `false` | 是否启用 Miaoda Inspector |
-| `NEED_ROUTES` | `boolean` | `true` | 是否需要路由解析 |
-| `CLIENT_BASE_PATH` | `string` | `/` | 客户端基础路径 |
-| `ASSETS_CDN_PATH` | `string` | `/` | 生产环境 CDN 路径 |
-| `SERVER_PORT` | `number` | `3000` | 服务器端口 |
-| `CLIENT_DEV_PORT` | `number` | `8080` | 客户端开发端口 |
-
-### createRecommendRspackConfig (传统版)
+### 环境变量说明
+
+| 变量 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `NODE_ENV` | string | `development` | 环境模式：development / production |
+| `ENABLE_REACT_REFRESH` | boolean | `false` | 是否启用 React 热更新 |
+| `NEED_ROUTES` | boolean | `true` | 是否需要路由解析 |
+| `CLIENT_BASE_PATH` | string | `/` | 客户端基础路径 |
+| `ASSETS_CDN_PATH` | string | `/` | 生产环境 CDN 路径 |
+| `SERVER_PORT` | number | `3000` | 服务器端口 |
+| `CLIENT_DEV_PORT` | number | `8080` | 客户端开发服务器端口 |
+
+## 内置功能
+
+### 1. TypeScript 和 React 支持
+- 自动处理 `.ts` / `.tsx` 文件
+- 支持 JSX 语法
+- SWC 编译器
+
+### 2. 样式处理
+- CSS 模块支持
+- PostCSS 处理
+- Tailwind CSS 支持
+
+### 3. 资源处理
+- 图片自动优化（SVG, PNG, JPG, GIF, WebP）
+- 小于 10KB 自动 inline
+
+### 4. 路由解析
+- 自动解析 React Router 路由
+- 生成 `routes.json` 文件
+- 通过 `NEED_ROUTES` 控制
+
+### 5. 开发服务器
+- HMR 热更新
+- API 代理到后端服务器
+- 热更新时间统计
+
+### 6. 模块别名优化
+- **clsx**: 自动集成 `tailwind-merge`
+- **echarts**: 优化导入路径
+
+## 对比两种方式
+
+| 特性 | extends | defineConfig |
+|------|---------|-------------|
+| 代码简洁度 | ✅ 更简洁 | 一般 |
+| TypeScript 类型 | 一般 | ✅ 更好 |
+| 动态配置 | ❌ 只能用环境变量 | ✅ 可以代码计算 |
+| 符合惯例 | ✅ 符合 webpack | 一般 |
+| 学习成本 | ✅ 低 | 一般 |
 
-提供更细粒度的控制，需要手动处理环境变量。
-
-```typescript
-function createRecommendRspackConfig(
-  options: CreateRecommendRspackConfigOptions
-): Configuration;
-
-interface CreateRecommendRspackConfigOptions {
-  isDev?: boolean;
-  enableReactRefresh?: boolean;
-  needRoutes?: boolean;
-  clientBasePath?: string;
-  publicPath?: string;
-}
-```
+## 迁移指南
 
-**示例：**
+### 从旧 API 迁移
 
+**之前（15+ 行）：**
 ```javascript
 const { createRecommendRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
 const { normalizeBasePath } = require('@lark-apaas/devtool-kits');
+const { merge } = require('webpack-merge');
 
 require('dotenv').config();
 
 const isDev = process.env.NODE_ENV !== 'production';
-
-module.exports = createRecommendRspackConfig({
+const baseConfig = createRecommendRspackConfig({
   isDev,
-  enableReactRefresh: true,
   clientBasePath: normalizeBasePath(process.env.CLIENT_BASE_PATH || '/'),
-  publicPath: isDev ? '/' : 'https://cdn.example.com',
+  publicPath: isDev ? '/' : process.env.ASSETS_CDN_PATH,
 });
-```
-
-## 内置插件和功能
-
-### 1. RouteParserPlugin
-
-自动解析 React Router 路由，生成 `routes.json` 文件。
-
-- **输入**：`./client/src/app.tsx`
-- **输出**：`dist/client/routes.json`
-- **控制**：`NEED_ROUTES` 环境变量
-
-### 2. SlardarPerformanceMonitorPlugin
-
-注入 Slardar 性能监控脚本到 HTML。
-
-- **位置**：`<head>` 标签末尾
-- **包含**：Slardar SDK + Performance 监控
-
-### 3. Module Alias
-
-#### clsx 别名
-将 `clsx` 替换为增强版本，自动集成 `tailwind-merge`：
-
-```javascript
-import { clsx } from 'clsx';  // 自动包含 twMerge 功能
-```
-
-#### echarts 别名
-优化 echarts 导入路径。
-
-### 4. HMR Timing Monitor
-
-开发模式下自动监控热更新时间，通过 WebSocket 推送给客户端。
 
-### 5. 代理配置
-
-自动配置开发服务器代理：
-- API 代理：`${CLIENT_BASE_PATH}/api` → `http://localhost:${SERVER_PORT}`
-- HTML 代理：所有 HTML 请求 → `http://localhost:${SERVER_PORT}`
-
-## 项目结构要求
-
-```
-your-project/
-├── .env                          # 环境变量配置
-├── rspack.config.js              # Rspack 配置
-├── client/
-│   ├── public/                   # 静态资源
-│   └── src/
-│       ├── app.tsx               # 路由定义（需包含 React Router）
-│       └── index.tsx             # 入口文件
-├── server/                       # 服务端代码
-└── dist/
-    └── client/                   # 构建产物
-        ├── routes.json           # 路由文件（自动生成）
-        └── ...
+module.exports = merge(baseConfig, {
+  entry: { main: './client/src/index.tsx' },
+});
 ```
 
-## 迁移指南
-
-### 从旧 API 迁移到新 API
-
-**之前（15 行）：**
-
+**现在（extends 方式，4 行）：**
 ```javascript
-const { defineConfig } = require('@rspack/cli');
-const { createRecommendRspackConfig } = require('@lark-apaas/fullstack-rspack-preset');
-const { normalizeBasePath } = require('@lark-apaas/devtool-kits');
-const { default: merge } = require('webpack-merge');
-
-require('dotenv').config();
-
-module.exports = defineConfig(({mode}) => {
-  const isDev = mode !== 'production';
-  const basePathWithoutTrailingSlash = normalizeBasePath(process.env.CLIENT_BASE_PATH || '/');
-  const publicPath = isDev ? '/' : process.env.ASSETS_CDN_PATH;
-
-  const baseConfig = createRecommendRspackConfig({
-    isDev,
-    clientBasePath: basePathWithoutTrailingSlash,
-    publicPath: publicPath,
-  });
-
-  return merge(baseConfig, {
-    entry: { main: './client/src/index.tsx' },
-  });
-});
+module.exports = {
+  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
+  entry: { main: './client/src/index.tsx' },
+};
 ```
 
-**现在（8 行）：**
-
+**或者（defineConfig 方式，6 行）：**
 ```javascript
-const path = require('path');
 const { defineConfig } = require('@lark-apaas/fullstack-rspack-preset');
 
 module.exports = defineConfig({
-  entry: {
-    main: './client/src/index.tsx',
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, 'client/src'),
-    },
-  },
+  entry: { main: './client/src/index.tsx' },
 });
 ```
 
 **迁移步骤：**
-
-1. 修改导入：`createRecommendRspackConfig` → `defineConfig`
+1. 选择使用方式（extends 或 defineConfig）
 2. 删除手动环境变量处理代码
-3. 删除 `defineConfig`、`normalizeBasePath`、`merge` 等导入
-4. 只保留覆盖配置（entry、resolve 等）
-5. 确保 `.env` 文件包含必要的环境变量
+3. 删除 `normalizeBasePath`、`merge` 等依赖
+4. 确保 `.env` 文件包含必要的环境变量
 
 ## 常见问题
 
-### Q: 如何禁用某个功能？
-
-通过环境变量控制：
-
-```bash
-# 禁用路由解析
-NEED_ROUTES=false
-
-# 禁用 React Refresh
-ENABLE_REACT_REFRESH=false
-```
+### Q: 如何自定义 webpack plugins？
 
-### Q: 如何自定义 DefinePlugin 变量？
-
-直接在 `overrides` 中添加：
+在配置中直接添加：
 
 ```javascript
-const { defineConfig } = require('@lark-apaas/fullstack-rspack-preset');
 const rspack = require('@rspack/core');
 
-module.exports = defineConfig({
+module.exports = {
+  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
   plugins: [
     new rspack.DefinePlugin({
-      'process.env.CUSTOM_VAR': JSON.stringify('custom-value'),
+      'process.env.CUSTOM_VAR': JSON.stringify('value'),
     }),
   ],
-});
+};
+```
+
+### Q: 如何禁用某个功能？
+
+通过环境变量：
+
+```bash
+# .env
+NEED_ROUTES=false              # 禁用路由解析
+ENABLE_REACT_REFRESH=false     # 禁用 React Refresh
 ```
 
-### Q: 如何使用生产环境 CDN？
+### Q: 生产环境如何使用 CDN？
 
 设置环境变量：
 
@@ -301,30 +236,39 @@ NODE_ENV=production
 ASSETS_CDN_PATH=https://cdn.example.com
 ```
 
-### Q: 为什么 DefinePlugin 没有生效？
+## API 文档
+
+### defineConfig
+
+```typescript
+function defineConfig(
+  overrides?: Partial<Configuration>
+): Configuration;
+```
+
+**参数：**
+- `overrides` - Rspack 配置对象，会与默认配置深度合并
 
-检查：
-1. `.env` 文件是否存在
-2. 环境变量名是否正确
-3. `process.env.runtimeMode` 缺少 `JSON.stringify`（已知问题，待修复）
+**返回：**
+- 完整的 Rspack 配置对象
 
-## 版本历史
+### createRecommendRspackConfig (旧版本 API)
 
-### 0.1.2-alpha.3
-- ✨ 新增 `defineConfig` API（对齐 rspack 官方）
-- ✨ 保持 `createFullstackRspackConfig` 向后兼容
-- 🐛 修复 .env 异步加载问题
+```typescript
+function createRecommendRspackConfig(
+  options: CreateRecommendRspackConfigOptions
+): Configuration;
 
-### 0.1.2-alpha.2
-- ✨ 新增 `createFullstackRspackConfig` 简化 API
-- ✨ 自动加载 `.env` 环境变量
-- ✨ 支持环境变量驱动配置
-- 🐛 修复 `@rspack/core` 版本冲突
-- 🐛 修复 Slardar 插件在 npm link 环境下的问题
-- 📝 完善文档和示例
+interface CreateRecommendRspackConfigOptions {
+  isDev?: boolean;
+  enableReactRefresh?: boolean;
+  needRoutes?: boolean;
+  clientBasePath?: string;
+  publicPath?: string;
+}
+```
 
-### 0.1.0
-- 🎉 初始版本
+> ⚠️ 建议迁移到 `defineConfig` 或 extends 方式
 
 ## License
 

package/lib/index.d.ts

@@ -35,4 +35,3 @@ import type { Configuration } from '@rspack/core';
  */
 export declare function createFullstackRspackConfig(overrides?: Partial<Configuration>): Configuration;
 export { createFullstackRspackConfig as defineConfig };
-export default createFullstackRspackConfig;

package/lib/index.js

@@ -71,5 +71,3 @@ function createFullstackRspackConfig(overrides = {}) {
     // 5. 深度合并用户配置
     return (0, webpack_merge_1.merge)(baseConfig, overrides);
 }
-// 默认导出
-exports.default = createFullstackRspackConfig;

package/lib/overlay/index.js

@@ -124,21 +124,51 @@ function removeAllChildren(element, skip) {
         element.removeChild(childList[i]);
     }
 }
+/**
+ * 降级复制方案（兼容旧浏览器）
+ * @param text 要复制的文本
+ * @returns boolean 复制是否成功
+ */
+function fallbackCopyToClipboard(text) {
+    try {
+        // 创建临时的 textarea 元素
+        const textArea = document.createElement('textarea');
+        textArea.value = text;
+        // 设置样式，使其不可见
+        textArea.style.position = 'fixed';
+        textArea.style.left = '-999999px';
+        textArea.style.top = '-999999px';
+        textArea.setAttribute('readonly', '');
+        // 添加到 DOM
+        document.body.appendChild(textArea);
+        // 选中文本
+        textArea.focus();
+        textArea.select();
+        // 执行复制命令
+        const successful = document.execCommand('copy');
+        // 清理：移除临时元素
+        document.body.removeChild(textArea);
+        return successful;
+    }
+    catch (error) {
+        console.error('降级复制方案失败:', error);
+        return false;
+    }
+}
 async function copyToClipboard(text) {
-    // 优先使用现代的 Clipboard API
-    if (navigator.clipboard && window.isSecureContext) {
-        try {
+    try {
+        // 优先使用现代的 Clipboard API
+        if (navigator.clipboard && window.isSecureContext) {
             await navigator.clipboard.writeText(text);
             return true;
         }
-        catch (error) {
-            // 权限被拒绝或其他错误，降级到 execCommand
-            console.warn('Clipboard API 失败，降级到 execCommand:', error);
-            return fallbackCopyToClipboard(text);
-        }
+        // 降级方案：使用传统的 execCommand 方法
+        return fallbackCopyToClipboard(text);
+    }
+    catch (error) {
+        // 执行navigator.clipboard.writeText失败时，降级方案
+        return fallbackCopyToClipboard(text);
     }
-    // 降级方案：使用传统的 execCommand 方法
-    return fallbackCopyToClipboard(text);
 }
 // 获取父窗口 origin
 function getPreviewParentOrigin() {
@@ -168,6 +198,10 @@ function render() {
             const origin = targetOrigin || getPreviewParentOrigin();
             window.parent.postMessage(message, origin);
         };
+        // 通知前端，渲染错误页面已准备就绪
+        sendPostMessage({
+            type: 'PreviewReady'
+        });
         // 通知主应用存在自定义 overlay
         sendPostMessage({
             type: 'app-features',

package/lib/preset.js

@@ -128,8 +128,7 @@ function createRecommendRspackConfig(options) {
                 'process.env.NODE_ENV': JSON.stringify(isDev ? 'development' : 'production'),
                 'process.env.runtimeMode': JSON.stringify('fullstack'),
                 'process.env.CLIENT_BASE_PATH': JSON.stringify(clientBasePath),
-                // FIXME:安全漏洞，会读取到服务路径，不应该在客户端代码中使用
-                'process.env.CWD': JSON.stringify(process.cwd()),
+                'process.env.CWD': JSON.stringify(''),
                 // 解决 window 未定义问题
                 'typeof window': JSON.stringify('object'),
                 window: 'globalThis',
@@ -316,7 +315,7 @@ function createRecommendRspackConfig(options) {
         output: {
             publicPath,
             path: path_1.default.resolve(rootDir, 'dist/client'),
-            clean: true,
+            clean: false,
             globalObject: 'this',
         },
     };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@lark-apaas/fullstack-rspack-preset",
-  "version": "0.1.2-alpha.6",
+  "version": "1.0.0",
   "files": [
-    "lib"
+    "lib",
+    "preset.config.js"
   ],
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

package/preset.config.js

@@ -0,0 +1,16 @@
+/**
+ * Rspack extends 专用配置文件
+ *
+ * 使用方式：
+ * ```javascript
+ * module.exports = {
+ *   extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
+ *   entry: { ... },
+ * }
+ * ```
+ */
+
+const { createFullstackRspackConfig } = require('./lib/index');
+
+// 直接导出配置对象（不是 exports.default）
+module.exports = createFullstackRspackConfig();

package/lib/react-refresh-plugin.d.ts

@@ -1,3 +0,0 @@
-export = createReactRefreshPlugin;
-declare function createReactRefreshPlugin(): ReactRefreshPlugin;
-import ReactRefreshPlugin = require("@rspack/plugin-react-refresh/dist");

package/lib/react-refresh-plugin.js

@@ -1,11 +0,0 @@
-"use strict";
-const ReactRefreshPlugin = require('@rspack/plugin-react-refresh');
-const path = require('path');
-function createReactRefreshPlugin() {
-    return new ReactRefreshPlugin({
-        overlay: {
-            module: path.resolve(__dirname, 'overlay/index.js'),
-        },
-    });
-}
-module.exports = createReactRefreshPlugin;