Rslib 1.0 正式发布：面向多场景的 JavaScript 库开发工具

我们很高兴地宣布 Rslib 1.0 已经正式发布！

Rslib 是一款基于 Rsbuild 的库开发工具，目标是帮助开发者用简单直接的方式开发各种类型的 JavaScript 库，包括工具库、UI 组件库、CLI 以及 Agent 应用等。

为什么需要 Rslib

Rslib 面向不同的库发布与消费场景，让库开发也能受益于应用构建中成熟的能力与生态。其核心优势体现在以下三个方面：

复用 Rspack 与 webpack 生态 ：Rslib 可以使用 Rsbuild 插件，以及 Rspack 和 webpack 生态中的许多插件与 loader。如果应用项目同样使用 Rsbuild 或 Rspack，开发者可以在应用与库之间共享配置和插件，并延续已有的工程经验，减少重复配置与维护成本。
支持构建模块联邦产物 ：除了 ESM、CJS 等常见格式，Rslib 还可以输出模块联邦产物，使库能够作为远程模块被多个应用在运行时加载，并提供配套的本地开发与联调能力。
统一的库构建流程：Rslib 可以在一次构建中完成 JavaScript 编译、框架语法转换、类型生成和静态资源处理，无需在多个工具之间切换或自行拼接构建流程。同时，Rslib 持续跟进 TypeScript 和框架生态的发展，支持 TypeScript 7 类型生成、React Compiler 等新能力。

从 0.x 到 1.0

自 Rslib 0.7 正式对外发布以来，我们先后发布了 16 个 minor 版本。在此期间，Rslib 推出了多项功能和优化，包括：

更快的构建与更小的产物 ：在包含 1 万个 React 组件的基准项目中，相较 Rslib 0.7.0，Rslib 1.0 的无缓存构建耗时减少约 24.3% ，有缓存构建耗时减少约 56.7% ，产物体积在 Gzip 前减少约 32.2% ，在 Gzip 后减少约 4.1%。

Rslib 版本生产构建（无缓存）生产构建（有缓存）产物体积（Gzip 前/后）

0.7.0 1.212 s 1.125 s 7.64 MiB / 1.40 MiB

1.0.0 0.918 s 0.487 s 5.19 MiB / 1.35 MiB
更快的类型生成 ：支持使用 TypeScript 7 或 Isolated Declarations 加快类型声明文件生成，实际收益会因项目而异。以 Rsbuild 仓库为例，不同方案的耗时如下：

方案耗时性能提升

TypeScript 6 9.7 s 基准

TypeScript 7 4.1 s 约 2.4 倍

Isolated Declarations 2.3 s 约 4.2 倍
更完整的组件库支持 ：支持构建 React、Vue、Svelte 或 Solid 组件库，并进一步完善样式与资源处理能力，覆盖 new URL()、Web Worker 和 Wasm 等场景。
更灵活的使用方式：简单项目无需配置文件即可构建，也可以根据需要编写配置；既可以通过 CLI 直接使用，也可以通过 JavaScript API 集成到脚本和其他工具中。

Rslib 版本	生产构建（无缓存）	生产构建（有缓存）	产物体积（Gzip 前/后）
0.7.0	1.212 s	1.125 s	7.64 MiB / 1.40 MiB
1.0.0	0.918 s	0.487 s	5.19 MiB / 1.35 MiB

方案	耗时	性能提升
TypeScript 6	9.7 s	基准
TypeScript 7	4.1 s	约 2.4 倍
Isolated Declarations	2.3 s	约 4.2 倍

更流畅的开发体验 ：可以与 Rstest、Rspress 和 Rsdoctor 配合完成测试、文档和产物诊断，并通过 Agent Skills 为 Coding Agent 提供 Rslib 相关最佳实践。

随着这些能力不断完善并经过大量生产项目的验证，Rslib 的配置结构与 JavaScript API 也逐步稳定。从 1.0 开始，Rslib 将以稳定的公开 API 为基础，遵循语义化版本（SemVer）规范持续演进。

面向不同场景的产物输出

一个库既可以作为 npm 包发布，也可以基于模块联邦构建为远程模块，供多个应用在运行时加载，从而实现独立部署和更新。常见的库构建工具主要面向 npm 包交付，而 Rslib 还支持构建模块联邦产物，并提供支持 HMR 的开发模式，便于与宿主应用或 Storybook 联调。

针对上述不同的运行环境和消费方式，Rslib 提供的产物格式如下：

产物格式	使用场景	使用方式
ESM、CJS	Node.js 与下游构建	由 Node.js 直接加载，或作为依赖交给应用构建工具继续处理
UMD、IIFE	浏览器直接加载	通过 `<script>` 标签在浏览器中直接使用
Module Federation	跨应用运行时加载	作为远程模块在运行时加载

需要同时生成多种格式的产物时，可以通过 format 配置分别指定，并在同一份配置中按需设置各自的构建方式，无需维护多套构建脚本。

在这些产物格式中，Rslib 对 ESM 产物进行了重点优化，使其对静态分析更友好并支持代码分割，方便下游构建工具进行 tree shaking 和二次构建。对于 ESM 产物中的 external 依赖，Rslib 也优化了默认处理方式，能够更准确地保留源码中的模块加载语义，减少构建转换带来的行为差异。

此外，除了常见的模块产物，Rslib 还提供了实验性的可执行文件生成能力。该能力基于 Node.js SEA，适用于 bundle 模式下的单入口 Node.js 产物。生成的可执行文件可以在未安装 Node.js 的目标系统中运行，适合分发 CLI 等 Node.js 程序。

灵活的构建模式

产物格式对应不同的加载方式，构建模式则决定库内部模块的组织方式。Rslib 支持 bundle 和 bundleless 两种构建模式，以适应不同的交付需求：

bundle 模式 （bundle: true）：Rslib 从入口出发，将内部模块打包为较少的文件，也可以结合代码分割按需输出多个 chunk，适合 SDK、CLI 和 Node.js 工具库等希望简化产物结构、便于分发的场景。
bundleless 模式 （bundle: false）：Rslib 逐个编译源文件，保留与源码对应的目录和模块结构，并处理模块引用、文件扩展名、样式与静态资源等，适合组件库、工具函数库和 monorepo 内部包，便于调试，也有利于下游进行按需加载和二次构建。

以一个包含三个源码文件的单入口库为例，两种模式的产物结构如下：

可以根据库的交付方式和使用场景选择合适的构建模式。需要兼顾不同消费场景时，也可以在同一个项目中分别生成 bundle 和 bundleless 产物。

快速的类型生成

对于 TypeScript 库，类型声明文件不仅影响编辑器中的类型提示，也关系到下游项目能否正确解析库的类型。通过 dts 配置，Rslib 可以在构建 JavaScript 产物的同时生成类型声明文件。在 bundleless 模式下，Rslib 还会根据实际产物处理声明文件中的路径别名和导入扩展名，使类型声明与 JavaScript 产物保持一致，并适配 NodeNext 等模块解析方式。

随着项目规模扩大，类型生成可能逐渐成为构建中的耗时环节。Rslib 提供了两种提速方式：

使用 TypeScript 7 ：当项目使用 TypeScript 7 及以上版本时，Rslib 会自动使用 native TypeScript (tsgo) 生成声明文件，在保留类型检查的同时加快类型生成。
使用 Isolated Declarations ：对于希望进一步缩短构建时间的项目，可以使用实验性的 Isolated Declarations 类型生成方式。Rslib 会在 Rspack 构建过程中，为构建依赖图中的模块快速生成声明文件，进一步减少类型生成的开销。

ts 复制代码

// rslib.config.ts
export default {
  dts: {
    isolated: true,
  },
};

需要注意的是，该模式不会执行类型检查，因此适合与独立的高性能类型检查流程配合使用。例如在 monorepo 中，日常构建由 Rslib 快速生成各个包的类型声明文件，并在 CI 或 pre-commit hook 中通过 rslint --type-check 统一执行完整的类型检查。

开箱即用的多框架支持

组件库是 Rslib 重点支持的场景之一。React、Vue、Svelte 和 Solid 在组件文件、编译方式和运行时约定上各有不同。Rslib 通过对应的 Rsbuild 插件接入这些框架的编译能力，产物格式、构建模式等库构建能力统一通过 Rslib 配置，框架语法则由相应的插件和编译器处理，使不同框架组件库可以沿用相近的配置方式和构建流程。

创建新项目时，可以通过 create-rslib 选择对应的框架模板，直接获得所需插件和基础配置；已有项目则可以按需注册相关插件。

以 React 组件库为例，注册 @rsbuild/plugin-react 后即可编译 JSX 和 TSX。通过该插件，还可以启用集成在 SWC 中的 Rust 版 React Compiler，在构建阶段自动优化组件代码，无需额外接入 Babel：

ts 复制代码

// rslib.config.ts
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  bundle: false,
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      reactCompiler: true,
    }),
  ],
});

对于希望将 JSX 交给应用侧继续编译的组件库，Rslib 也支持在 bundleless 模式下保留 JSX 并输出 .jsx 文件，由下游应用根据自身的目标环境和构建配置完成转换。

查看 React 方案、Vue 方案、Svelte 方案、Solid 方案了解更多。

丰富的样式与资源处理

Rslib 可以在构建 JavaScript 产物的同时处理样式、静态资源、Web Worker 和 Wasm，并根据产物格式和构建配置处理文件之间的引用关系，使生成的产物既可以被直接使用，也可以交由下游构建工具继续处理。

样式

Rslib 开箱支持 CSS Modules、PostCSS、样式提取、内联和压缩等能力，并会根据构建模式选择合适的样式输出方式；Sass、Less、Stylus 和 Tailwind CSS 则可通过 Rsbuild 插件接入。

js 复制代码

import './style.scss';
import styles from './button.module.css';

静态资源

图片、字体和音视频等静态资源可以在 JavaScript 中通过 import 引用，也可以在 CSS 中通过 url() 使用。对于 JSON 文件，Rslib 支持使用 Import Attributes 将其作为 JSON 模块导入。此外，还可以使用 new URL() 引用本地资源，Rslib 会输出相应文件并更新产物中的引用路径。

js 复制代码

import data from './data.json' with { type: 'json' };
import logo from './logo.svg';

const dataFile = new URL('./data.txt', import.meta.url);

Web Worker 与 Wasm

Rslib 可以识别标准的 Web Worker 声明，构建 Worker 入口及其依赖，无需额外维护入口和复制脚本。对于 Wasm，Rslib 支持 WebAssembly ESM Integration 和 Source Phase Imports 等语法，既可以生成加载和实例化所需的代码，也可以保留 Wasm import，交给支持相应能力的下游构建工具或目标运行时继续处理。

js 复制代码

import { add } from './add.wasm';
import source addModule from './add.wasm';

const worker = new Worker(new URL('./worker.ts', import.meta.url));

查看 CSS、静态资源、Web Workers 和 Wasm 了解更多。

按需扩展的使用方式

对于简单项目，Rslib 支持通过命令行参数直接构建，无需创建配置文件：

bash 复制代码

npx rslib build --entry src/index.ts --format esm --dts

随着构建需求增加，可以再通过配置文件控制更多构建行为。Rslib 1.0 简化了配置结构：如果只需生成一份默认的 ESM 产物，可以省略 lib 字段，直接在顶层编写配置；需要输出多份产物时，则通过 lib 数组分别设置每份产物的格式和构建方式。

多个产物共用的 syntax、plugins 等配置可以放在顶层，各个 lib 只需配置不同的部分，也可以按需覆盖顶层配置，减少重复。

ts 复制代码

// rslib.config.ts
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
    {
      format: 'cjs',
      syntax: 'es2020',
    },
  ],
  // 应用于所有产物，可在 lib 中单独覆盖
  syntax: 'es2023',
});

如果需要在脚本或其他工具中使用 Rslib，可以通过 JavaScript API 创建实例并执行构建，例如批量构建工作区中的多个包、封装内部构建命令或接入发布流水线。JavaScript API 可以在 Node.js、Deno 和 Bun 中使用：

ts 复制代码

import { createRslib } from '@rslib/core';

const rslib = await createRslib();
const result = await rslib.build();

await result.close();

协同的库开发流程

Rslib 可以与 Rstack 生态中的工具和插件配合，覆盖库开发流程中的功能测试、文档开发、构建分析和发布前检查等环节。

测试

使用 create-rslib 创建的新项目默认配置了 Rstest。通过 @rstest/adapter-rslib，Rstest 可以复用 Rslib 的相关配置，减少重复维护，也让测试时的模块解析和源码处理更接近实际构建。

ts 复制代码

// rstest.config.ts
import { withRslibConfig } from '@rstest/adapter-rslib';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  extends: withRslibConfig(),
});

文档

Rslib 项目可以使用 Rspress 搭建文档站点。对于组件库，可以使用 @rspress/plugin-preview 在 MDX 中编写可运行的组件示例，并通过 @rspress/plugin-api-docgen 从源码生成组件 API 文档，方便在同一站点中维护使用说明、组件示例和 API 信息。

产物检查

发布前，可以通过 rsbuild-plugin-publint 检查 package.json、包结构和导出配置等常见问题，并通过 rsbuild-plugin-arethetypeswrong 检查类型声明能否在不同的模块解析方式下正确使用。这些检查可以只在 CI 环境中启用：

ts 复制代码

// rslib.config.ts
import { defineConfig } from '@rslib/core';
import { pluginAreTheTypesWrong } from 'rsbuild-plugin-arethetypeswrong';
import { pluginPublint } from 'rsbuild-plugin-publint';

export default defineConfig({
  dts: true,
  plugins: [
    pluginPublint({
      enable: Boolean(process.env.CI),
    }),
    pluginAreTheTypesWrong({
      enable: Boolean(process.env.CI),
    }),
  ],
});

构建分析

需要进一步分析构建过程和产物时，可以使用 Rsdoctor 查看构建耗时、依赖关系和产物体积，帮助定位构建性能、依赖体积和产物结构方面的问题。

查看使用 Rstest、使用 Rspress、使用 Rsdoctor 了解更多。

Agent 友好的开发体验

随着 Coding Agent 越来越多地参与到日常开发流程中，为其提供准确的工具知识和项目上下文也变得更加重要。

为此，Rslib 提供了面向 Agent 的 Skills：

rslib-best-practices：提供 Rslib 项目配置与构建的最佳实践。
rslib-modern-package：提供现代 JavaScript 包的设计和发布建议。
migrate-to-rslib：辅助将使用 tsc 或 tsup 构建的项目迁移到 Rslib。

在支持 Skills 的 Coding Agent 中，可以为已有项目安装指定的 Skill，也可以在使用 create-rslib 创建新项目时直接完成安装：

bash 复制代码

# 为已有项目安装
npx skills add rstackjs/agent-skills --skill rslib-best-practices

# 创建新项目时安装
npx -y create-rslib@latest my-project -t react --skill rslib-best-practices

除了 Skills，Rslib 官网文档还提供了 llms.txt 和 llms-full.txt，分别用于按需查找文档和获取完整的文档上下文。每个文档页面也提供对应的 Markdown 版本，方便将特定内容提供给 Agent。

通过 create-rslib 创建的新项目还会包含 AGENTS.md，其中记录了常用命令和相关文档入口。开发者可以在此基础上继续补充项目结构、开发流程和工程约定，让 Agent 同时了解 Rslib 的通用实践和当前项目的具体上下文。

查看 AI 了解更多。

如何使用 Rslib 1.0

如果你还未使用过 Rslib，可以通过 StackBlitz 示例来体验，也可以参考快速上手创建一个新的 Rslib 项目。
如果你正在使用 Rslib 0.x，请留意 1.0 版本包含一些不兼容更新，可以参考从 0.x 升级到 v1 文档进行升级。
如果你计划从 tsc、tsup 等工具迁移到 Rslib，可以参考从现有项目迁移。

下一步

Rslib 1.0 是一个稳定起点，而不是终点。接下来，我们会继续围绕两个方向推进：

持续提升构建与产物能力，包括优化 ESM 和 CJS 产物、探索更完整的 Node.js 打包能力与更灵活的模块结构保留方式，并持续提升类型生成和打包的效率与体验。
完善库开发工作流，加强 Rslib 与测试、文档、质量检查和发布流程的协同，减少不同环节之间的重复配置与维护工作。

致谢

Rslib 的部分实现和 API 设计参考或改编自 esbuild、mini-css-extract-plugin、tsdown、tsup 和 webpack 等优秀开源项目，感谢这些项目及其贡献者所提供的经验、思路与实现。

Rslib 的成长也离不开社区中的每一份参与，感谢所有为 Rslib 贡献代码和文档、提交 Issue、参与讨论和分享反馈的开发者，以及每一位选择和使用 Rslib 的用户。

在使用 Rslib 的过程中如果遇到问题或有任何建议，欢迎通过 GitHub Issues、GitHub Discussions 或社区渠道与我们交流。