@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 监控、代理配置

安装

npm install @lark-apaas/fullstack-rspack-preset

使用方式

方式 1: extends（推荐给简单场景）

类似 ESLint、TypeScript 的配置继承方式：

// 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（推荐给复杂场景）

函数式调用，更灵活：

// 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 文件：

# 环境模式
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+ 行）：

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 行）：

module.exports = {
  extends: '@lark-apaas/fullstack-rspack-preset/preset.config.js',
  entry: { main: './client/src/index.tsx' },
};

或者（defineConfig 方式，6 行）：

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？

在配置中直接添加：

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: 如何禁用某个功能？

通过环境变量：

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

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

设置环境变量：

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

API 文档

defineConfig

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

参数：

• overrides - Rspack 配置对象，会与默认配置深度合并

返回：

• 完整的 Rspack 配置对象

createRecommendRspackConfig (旧版本 API)

function createRecommendRspackConfig(
  options: CreateRecommendRspackConfigOptions
): Configuration;

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

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

License

MIT