Rslib 1.0: Build JS Libraries Faster with Module Federation & 4x Type Generation

Rslib 1.0 is a library development tool built on Rsbuild, designed to build JavaScript libraries including utility libraries, UI component libraries, CLIs, and Agent applications.

Why Rslib

Rslib targets different library publishing and consumption scenarios, allowing library development to benefit from mature application build capabilities and ecosystem. Its core advantages are threefold:

Reuse Rspack and webpack ecosystem : Rslib can use Rsbuild plugins, as well as many plugins and loaders from the Rspack and webpack ecosystems. If the application project also uses Rsbuild or Rspack, developers can share configurations and plugins between application and library, extending existing engineering experience and reducing duplicate configuration and maintenance costs.

Support building Module Federation artifacts : Beyond common formats like ESM and CJS, Rslib can output Module Federation artifacts, enabling libraries to be loaded as remote modules by multiple applications at runtime, with accompanying local development and debugging capabilities.

Unified library build process : Rslib completes JavaScript compilation, framework syntax transformation, type generation, and static asset handling in a single build, eliminating the need to switch between multiple tools or manually stitch build pipelines. Rslib continuously tracks TypeScript and framework ecosystem evolution, supporting TypeScript 7 type generation, React Compiler, and other new capabilities.

From 0.x to 1.0

Since Rslib 0.7 was officially released, 16 minor versions have been shipped, introducing numerous features and optimizations:

Faster builds and smaller artifacts

In a benchmark project containing 10,000 React components, compared to Rslib 0.7.0, Rslib 1.0 reduces no-cache build time by ~24.3%, cached build time by ~56.7%, artifact size before gzip by ~32.2%, and after gzip by ~4.1%.

Rslib version | Production build (no cache) | Production build (cache) | Artifact size (pre-gzip / post-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

Faster type generation

Support for TypeScript 7 or Isolated Declarations accelerates declaration file generation; actual gains vary by project. Using the Rsbuild repository as an example:

Approach             | Time   | Speedup
TypeScript 6         | 9.7 s  | baseline
TypeScript 7 (tsgo)  | 4.1 s  | ~2.4x
Isolated Declarations| 2.3 s  | ~4.2x

Isolated Declarations mode skips type checking, so it suits pairing with a separate high-performance type-checking step (e.g., rslint --type-check in CI or pre-commit hooks).

More complete component library support

Supports building React, Vue, Svelte, or Solid component libraries, with improved styling and asset handling covering new URL(), Web Workers, and Wasm scenarios.

More flexible usage

Simple projects build without a config file; complex needs can be configured. Rslib works via CLI or JavaScript API for integration into scripts and other tools.

Smoother developer experience

Integrates with Rstest, Rspress, and Rsdoctor for testing, documentation, and artifact diagnostics. Agent Skills provide Rslib best practices for Coding Agents.

With these capabilities validated in many production projects, Rslib's configuration structure and JavaScript API have stabilized. From 1.0 onward, Rslib follows SemVer with a stable public API.

Output Formats for Different Scenarios

A library can be published as an npm package or built as a remote module via Module Federation for runtime loading by multiple applications, enabling independent deployment and updates. While most library build tools focus on npm package delivery, Rslib also supports Module Federation artifacts with an HMR-enabled dev mode for debugging with host applications or Storybook.

Rslib provides the following artifact formats:

ESM, CJS — Node.js and downstream builds; loaded directly by Node.js or passed to application build tools.

UMD, IIFE — Browser direct loading; used via <script> tags in the browser.

Module Federation — Cross-application runtime loading; loaded as remote modules at runtime.

Multiple formats can be generated simultaneously via the format configuration, each with its own build settings, without maintaining separate build scripts. Rslib optimizes ESM artifacts for static analysis friendliness and code splitting, facilitating tree shaking and downstream rebuilds. External dependencies in ESM output are handled to preserve source module loading semantics more accurately.

Additionally, Rslib offers experimental executable file generation based on Node.js SEA, suitable for single-entry Node.js artifacts in bundle mode. The resulting executable runs on target systems without Node.js installed, ideal for distributing CLIs.

Flexible Build Modes

Artifact formats correspond to different loading methods; build modes determine internal module organization. Rslib supports two modes:

Bundle mode ( bundle: true): Rslib bundles internal modules from entry points into fewer files, optionally splitting into multiple chunks via code splitting. Suits SDKs, CLIs, and Node.js utility libraries where simplified artifact structure and easy distribution are desired.

Bundleless mode ( bundle: false): Rslib compiles each source file individually, preserving the source directory and module structure, handling module references, file extensions, styles, and static assets. Suits component libraries, utility function libraries, and monorepo internal packages, aiding debugging and enabling downstream on-demand loading and rebuilds.

The diagram illustrates output structures for a single-entry library with three source files under each mode. Choose the mode based on delivery and consumption scenarios; both can be generated in the same project when needed.

Fast Type Generation

For TypeScript libraries, declaration files affect editor type hints and downstream type resolution. Via the dts configuration, Rslib generates declaration files alongside JavaScript artifacts. In bundleless mode, Rslib adjusts path aliases and import extensions in declarations to match the JavaScript output and adapt to NodeNext module resolution.

As projects grow, type generation can become a build bottleneck. Rslib provides two acceleration paths:

Use TypeScript 7 : When the project uses TypeScript 7+, Rslib automatically employs native TypeScript (tsgo) to generate declarations while retaining type checking.

Use Isolated Declarations : For further build-time reduction, the experimental Isolated Declarations mode generates declarations during the Rspack build for modules in the dependency graph, further cutting type generation overhead.

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

This mode does not perform type checking, so it pairs well with a separate type-checking pipeline (e.g., rslint --type-check in CI or pre-commit hooks).

Out-of-the-Box Multi-Framework Support

Component libraries are a key Rslib scenario. React, Vue, Svelte, and Solid differ in component files, compilation, and runtime conventions. Rslib integrates each framework's compilation capabilities via corresponding Rsbuild plugins, while artifact formats, build modes, and other library build capabilities are unified through Rslib configuration. This lets different framework component libraries share similar configuration patterns and build flows.

New projects can use create-rslib to select a framework template, obtaining required plugins and base config; existing projects can register plugins as needed.

For a React component library, registering @rsbuild/plugin-react enables JSX/TSX compilation. The plugin also activates the Rust-based React Compiler integrated in SWC, automatically optimizing component code at build time without extra Babel setup:

// 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,
    }),
  ],
});

For libraries that want downstream applications to compile JSX, Rslib supports preserving JSX in bundleless mode and outputting .jsx files for downstream transformation.

See React solution, Vue solution, Svelte solution, Solid solution for details.

Rich Styling and Asset Handling

Rslib processes styles, static assets, Web Workers, and Wasm while building JavaScript artifacts, handling cross-file references according to artifact format and build config so outputs are directly usable or further processable by downstream tools.

Styles

Rslib supports CSS Modules, PostCSS, style extraction, inlining, and minification out of the box, choosing appropriate style output per build mode. Sass, Less, Stylus, and Tailwind CSS are available via Rsbuild plugins.

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

Static Assets

Images, fonts, audio/video can be imported in JavaScript via import or in CSS via url(). JSON files support Import Attributes for JSON module imports. new URL() references local assets; Rslib emits the files and updates reference paths in artifacts.

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

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

Web Workers and Wasm

Rslib recognizes standard Web Worker declarations, building the worker entry and its dependencies without extra entry maintenance or copy scripts. For Wasm, Rslib supports WebAssembly ESM Integration and Source Phase Imports, generating load/instantiation code or preserving Wasm imports for downstream tools or runtimes that support them.

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

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

See CSS, Static Assets, Web Workers, Wasm for more.

On-Demand Extensible Usage

For simple projects, Rslib builds directly via command-line arguments without a config file:

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

As needs grow, a config file controls more behavior. Rslib 1.0 simplifies config structure: for a single default ESM artifact, omit the lib field and write config at the top level; for multiple artifacts, use a lib array to set each artifact's format and build mode. Shared syntax, plugins, etc., stay at the top level; each lib entry configures only differences and can override top-level settings.

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

export default defineConfig({
  lib: [
    { format: 'esm' },
    { format: 'cjs', syntax: 'es2020' },
  ],
  syntax: 'es2023',
});

For programmatic use, the JavaScript API creates instances and runs builds, enabling batch building of workspace packages, wrapping internal build commands, or integrating into release pipelines. The API works in Node.js, Deno, and Bun:

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

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

await result.close();

Collaborative Library Development Workflow

Rslib integrates with Rstack ecosystem tools and plugins to cover functional testing, documentation, build analysis, and pre-publish checks.

Testing

Projects created with create-rslib include Rstest by default. Via @rstest/adapter-rslib, Rstest reuses Rslib configuration, reducing duplicate maintenance and aligning test-time module resolution and source handling with actual builds.

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

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

Documentation

Rslib projects can use Rspress for documentation sites. For component libraries, @rspress/plugin-preview enables runnable component examples in MDX, and @rspress/plugin-api-docgen generates component API docs from source, keeping usage guides, examples, and API info in one site.

Artifact Checks

Before publishing, rsbuild-plugin-publint validates package.json, package structure, and exports config; rsbuild-plugin-arethetypeswrong verifies type declarations work across module resolution modes. These checks can run only in CI:

// 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),
    }),
  ],
});

Build Analysis

For deeper build and artifact analysis, Rsdoctor visualizes build timings, dependency graphs, and artifact sizes, helping diagnose build performance, dependency bloat, and artifact structure issues.

See Using Rstest, Using Rspress, Using Rsdoctor.

Agent-Friendly Developer Experience

As Coding Agents join daily workflows, providing accurate tool knowledge and project context becomes crucial. Rslib offers Agent-oriented Skills:

rslib-best-practices : Rslib project configuration and build best practices.

rslib-modern-package : Modern JavaScript package design and publishing guidance.

migrate-to-rslib : Assists migrating projects from tsc or tsup to Rslib.

In Skill-supporting Coding Agents, install a Skill for an existing project or during create-rslib project creation:

# Install for existing project
npx skills add rstackjs/agent-skills --skill rslib-best-practices

# Install when creating new project
npx -y create-rslib@latest my-project -t react --skill rslib-best-practices

Beyond Skills, Rslib docs provide llms.txt and llms-full.txt for on-demand doc lookup and full context retrieval. Each doc page also offers a Markdown version for feeding specific content to Agents. Projects created with create-rslib include an AGENTS.md file recording common commands and doc links; developers can extend it with project structure, workflows, and conventions so Agents understand both Rslib general practices and project-specific context.

See AI for more.

How to Use Rslib 1.0

New to Rslib? Try the StackBlitz example or follow the Quick Start to create a project.

Upgrading from Rslib 0.x? Note 1.0 includes breaking changes; see the 0.x to v1 upgrade guide.

Migrating from tsc, tsup, etc.? Refer to Migrating from existing projects.

Next Steps

Rslib 1.0 is a stable starting point, not the finish line. Development will continue in two directions:

Continuously improve build and artifact capabilities : optimize ESM and CJS outputs, explore more complete Node.js bundling and flexible module structure preservation, and keep improving type generation and bundling efficiency and experience.

Refine the library development workflow : strengthen Rslib collaboration with testing, documentation, quality checks, and release processes, reducing duplicate configuration and maintenance across stages.

Acknowledgements

Parts of Rslib's implementation and API design reference or adapt from excellent open-source projects including esbuild, mini-css-extract-plugin, tsdown, tsup, and webpack. Thanks to these projects and their contributors for experience, ideas, and implementations.

Rslib's growth relies on community participation. Thanks to all who contributed code and docs, filed issues, joined discussions, shared feedback, and every user who chose Rslib.

For issues or suggestions, reach out via GitHub Issues, GitHub Discussions, or community channels.