# @lark-apaas/fullstack-rspack-preset

> 开箱即用的 Fullstack Rspack 配置预设

提供开箱即用的 Rspack 配置，包含 TypeScript、React、路由解析、HMR 等完整功能。

## 特性

- ✅ **零配置** - 环境变量驱动，开箱即用
- ✅ **两种使用方式** - 支持 extends 继承和 defineConfig 函数
- ✅ **TypeScript** - 完整的类型定义和 TSX 支持
- ✅ **React Refresh** - 支持 React 快速刷新
- ✅ **路由解析** - 自动解析 React Router 路由
- ✅ **模块优化** - clsx + tailwind-merge、echarts 别名
- ✅ **开发体验** - HMR 监控、代理配置

## 安装

```bash
npm install @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 惯例
- ✅ 配置自动深度合并

---

### 方式 2: defineConfig（推荐给复杂场景）

函数式调用，更灵活：

```javascript
// rspack.config.js
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'),
    },
  },
});
```

**特点：**
- ✅ TypeScript 类型推断更好
- ✅ 可以动态计算配置
- ✅ 更灵活的配置方式

---

## 环境变量配置

在项目根目录创建 `.env` 文件：

```bash
# 环境模式
NODE_ENV=development

# 功能开关
ENABLE_REACT_REFRESH=true
NEED_ROUTES=true

# 路径配置
CLIENT_BASE_PATH=/
ASSETS_CDN_PATH=https://cdn.example.com

# 端口配置
SERVER_PORT=3000
CLIENT_DEV_PORT=8080
```

### 环境变量说明

| 变量 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `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 | 一般 |
| 学习成本 | ✅ 低 | 一般 |

## 迁移指南

### 从旧 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';
const baseConfig = createRecommendRspackConfig({
  isDev,
  clientBasePath: normalizeBasePath(process.env.CLIENT_BASE_PATH || '/'),
  publicPath: isDev ? '/' : process.env.ASSETS_CDN_PATH,
});

module.exports = merge(baseConfig, {
  entry: { main: './client/src/index.tsx' },
});
```

**现在（extends 方式，4 行）：**
```javascript
module.exports = {
  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
  entry: { main: './client/src/index.tsx' },
};
```

**或者（defineConfig 方式，6 行）：**
```javascript
const { defineConfig } = require('@lark-apaas/fullstack-rspack-preset');

module.exports = defineConfig({
  entry: { main: './client/src/index.tsx' },
});
```

**迁移步骤：**
1. 选择使用方式（extends 或 defineConfig）
2. 删除手动环境变量处理代码
3. 删除 `normalizeBasePath`、`merge` 等依赖
4. 确保 `.env` 文件包含必要的环境变量

## 常见问题

### Q: 如何自定义 webpack plugins？

在配置中直接添加：

```javascript
const rspack = require('@rspack/core');

module.exports = {
  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
  plugins: [
    new rspack.DefinePlugin({
      'process.env.CUSTOM_VAR': JSON.stringify('value'),
    }),
  ],
};
```

### Q: 如何禁用某个功能？

通过环境变量：

```bash
# .env
NEED_ROUTES=false              # 禁用路由解析
ENABLE_REACT_REFRESH=false     # 禁用 React Refresh
```

### Q: 生产环境如何使用 CDN？

设置环境变量：

```bash
NODE_ENV=production
ASSETS_CDN_PATH=https://cdn.example.com
```

## API 文档

### defineConfig

```typescript
function defineConfig(
  overrides?: Partial<Configuration>
): Configuration;
```

**参数：**
- `overrides` - Rspack 配置对象，会与默认配置深度合并

**返回：**
- 完整的 Rspack 配置对象

### createRecommendRspackConfig (旧版本 API)

```typescript
function createRecommendRspackConfig(
  options: CreateRecommendRspackConfigOptions
): Configuration;

interface CreateRecommendRspackConfigOptions {
  isDev?: boolean;
  enableReactRefresh?: boolean;
  needRoutes?: boolean;
  clientBasePath?: string;
  publicPath?: string;
}
```

> ⚠️ 建议迁移到 `defineConfig` 或 extends 方式

## License

MIT