#@esmx/rspack

Rspack 包提供了一套用于创建和配置 Rspack 应用的 API，支持标准应用和 HTML 应用的构建与开发。

#安装

使用包管理器安装 @esmx/rspack 开发依赖：

npm install @esmx/rspack -D

yarn add @esmx/rspack -D

pnpm add @esmx/rspack -D

bun add @esmx/rspack -D

deno add npm:@esmx/rspack -D

#类型导出

#BuildTarget

type BuildTarget = 'node' | 'client' | 'server'

构建目标环境类型，定义了应用程序的构建目标环境：

• node: 构建为 Node.js 环境运行的代码
• client: 构建为浏览器环境运行的代码
• server: 构建为服务端环境运行的代码

#RspackAppConfigContext

interface RspackAppConfigContext {
  esmx: Esmx
  buildTarget: BuildTarget
  config: RspackOptions
  options: RspackAppOptions
}

Rspack 应用配置上下文接口，提供了在配置钩子函数中可以访问的上下文信息：

• esmx: Esmx 框架实例
• buildTarget: 当前的构建目标（client/server/node）
• config: Rspack 配置对象
• options: 应用配置选项

#RspackAppChainContext

interface RspackAppChainContext {
  esmx: Esmx
  buildTarget: BuildTarget
  chain: import('rspack-chain').RspackChain
  options: RspackAppOptions
}

Rspack 应用链式配置上下文接口，用于 chain 钩子函数：

• esmx: Esmx 框架实例
• buildTarget: 当前的构建目标（client/server/node）
• chain: rspack-chain 配置对象，可通过链式 API 修改 Rspack 配置
• options: 应用配置选项

#RspackAppOptions

interface RspackAppOptions {
  minimize?: boolean
  config?: (context: RspackAppConfigContext) => void
  chain?: (context: RspackAppChainContext) => void
}

Rspack 应用配置选项接口：

• minimize: 是否启用代码压缩，true 启用，false 禁用，undefined 根据环境自动决定（生产环境启用，开发环境禁用）
• config: 配置钩子函数，在构建开始前调用，可修改 Rspack 编译配置
• chain: 链式配置钩子函数，使用 rspack-chain 提供更灵活的配置修改方式

#RspackHtmlAppOptions

继承自 RspackAppOptions，用于配置 HTML 应用的特定选项：

interface RspackHtmlAppOptions extends RspackAppOptions {
  css?: 'css' | 'js' | false
  loaders?: Partial<Record<keyof typeof RSPACK_LOADER, string>>
  styleLoader?: Record<string, any>
  cssLoader?: Record<string, any>
  lessLoader?: Record<string, any>
  styleResourcesLoader?: Record<string, any>
  swcLoader?: SwcLoaderOptions
  definePlugin?: Record<string, string | Partial<Record<BuildTarget, string>>>
  target?: TargetSetting
}

• css: CSS 输出方式，可选 'css'（独立文件）或 'js'（打包到 JS 中），默认根据环境自动选择
• loaders: 自定义 loader 配置，可替换默认 loader 实现
• styleLoader: style-loader 配置选项
• cssLoader: css-loader 配置选项
• lessLoader: less-loader 配置选项
• styleResourcesLoader: 全局样式资源自动注入配置
• swcLoader: SWC loader 配置选项
• definePlugin: 全局常量定义
• target: 构建目标兼容性配置

#函数导出

#createRspackApp

function createRspackApp(esmx: Esmx, options?: RspackAppOptions): Promise<App>

创建一个标准的 Rspack 应用实例。

参数：

• esmx — Esmx 框架实例
• options — Rspack 应用配置选项

返回值：

• 返回一个 Promise，解析为创建的应用实例

#createRspackHtmlApp

function createRspackHtmlApp(esmx: Esmx, options?: RspackHtmlAppOptions): Promise<App>

创建一个 HTML 类型的 Rspack 应用实例。

参数：

• esmx — Esmx 框架实例
• options — HTML 应用配置选项

返回值：

• 返回一个 Promise，解析为创建的 HTML 应用实例

#常量导出

#RSPACK_LOADER

const RSPACK_LOADER: Record<string, string> = {
  builtinSwcLoader: 'builtin:swc-loader',
  lightningcssLoader: 'builtin:lightningcss-loader',
  styleLoader: 'style-loader',
  cssLoader: 'css-loader',
  lessLoader: 'less-loader',
  styleResourcesLoader: 'style-resources-loader',
  workerRspackLoader: 'worker-rspack-loader'
}

Rspack 内置的 loader 标识符映射对象，提供了常用的 loader 名称常量：

• builtinSwcLoader: Rspack 内置的 SWC loader，用于处理 TypeScript/JavaScript 文件
• lightningcssLoader: Rspack 内置的 LightningCSS loader，用于处理 CSS 文件的高性能编译器
• styleLoader: 用于将 CSS 注入到 DOM 中的 loader
• cssLoader: 用于解析 CSS 文件和处理 CSS 模块化的 loader
• lessLoader: 用于将 Less 文件编译为 CSS 的 loader
• styleResourcesLoader: 用于自动导入全局样式资源（如变量、mixins）的 loader
• workerRspackLoader: 用于处理 Web Worker 文件的 loader

使用这些常量可以在配置中引用内置的 loader，避免手动输入字符串：

import { RSPACK_LOADER } from '@esmx/rspack';

export default {
  async devApp(esmx) {
    return import('@esmx/rspack').then((m) =>
      m.createRspackHtmlApp(esmx, {
        loaders: {
          // 使用常量引用 loader
          styleLoader: RSPACK_LOADER.styleLoader,
          cssLoader: RSPACK_LOADER.cssLoader,
          lightningcssLoader: RSPACK_LOADER.lightningcssLoader
        }
      })
    );
  }
};

注意事项：

• 这些 loader 已经内置在 Rspack 中，无需额外安装
• 在自定义 loader 配置时，可以使用这些常量来替换默认的 loader 实现
• 某些 loader（如 builtinSwcLoader）有特定的配置选项，请参考相应的配置文档

#模块导出

#rspack

重导出 @rspack/core 包的所有内容，提供完整的 Rspack 核心功能。