---
url: /guide/start/index.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Introduction
Rslib is a library development tool based on [Rsbuild](https://rsbuild.rs).
It gives developers a simple way to create JavaScript libraries and UI component libraries, and provides tool integrations and best practices for building, debugging, documentation, and testing throughout library development.
## Why Rslib
During the development of component or utility libraries, developers need to focus not only on implementing project logic, but also on handling tasks that are separate from the code itself, such as building, debugging, documentation, and testing. Although many community tools and solutions can address some of these needs, developers who are not familiar with them often face cumbersome configuration requirements or need to coordinate multiple tools to meet these demands.
Based on Rspack and Rsbuild, Rslib offers a comprehensive solution tailored to the diverse requirements of library development, effectively addressing issues such as incomplete tool ecosystems, high costs for module standard compatibility, and insufficient output optimization. Rslib optimizes webpack's limited support for library ESM outputs, reducing redundant runtime code and generating high-quality ESM outputs that are tree-shaking friendly for library consumers. Additionally, Rslib fully leverages the build performance advantages of Rspack and capitalizes the strengths of both the webpack and Rspack ecosystems to robustly support features such as Module Federation.
Furthermore, Rslib utilizes Rsbuild's out-of-the-box configuration to facilitate configuration sharing between application and library projects, resolving the challenge of reusing build configurations between application projects and library projects, thereby reducing the configuration overhead for developers and improving development efficiency and experience.
In the future, Rslib will explore additional possibilities by leveraging the new features of Rspack.
## Features
Rslib has the following features:
- **Easy to configure**: Out-of-the-box tooling enables developers to build libraries with zero configuration. Rslib also provides a set of semantic build configurations that can be extended as project needs grow.
- **Performance-focused**: Powered by [Rspack](https://rspack.rs), it integrates high-performance Rust-based tools from the community, including [SWC](https://swc.rs/) and [Lightning CSS](https://lightningcss.dev/), delivering first-class build speed and development experience.
- **Plugin ecosystem**: Supports [Rsbuild plugins](https://rsbuild.rs/plugins/list/), Rspack plugins, and webpack plugins, allowing developers to reuse existing plugin ecosystems and continue using familiar development workflows and engineering practices.
- **Flexible outputs**: Designed around the diverse ways libraries are published and consumed, it supports flexible build output configuration for different runtimes, distribution methods, and downstream build tools to meet the delivery needs of different types of libraries.
- **Framework agnostic**: Decoupled from frontend UI frameworks, it supports React, Vue, Svelte, Solid, and other frameworks through plugins, allowing developers to build component libraries for different frameworks with a consistent configuration and development workflow.
## Rstack
Rslib is part of Rstack, the fast, unified JavaScript toolchain for developers and agents.
Rstack includes the following tools:
| Name | Description | Version |
| ----------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Rspack](https://github.com/web-infra-dev/rspack) | Bundler | 
|
| [Rsbuild](https://github.com/web-infra-dev/rsbuild) | Build tool | 
|
| [Rslib](https://github.com/web-infra-dev/rslib) | Library development tool | 
|
| [Rspress](https://github.com/web-infra-dev/rspress) | Static site generator | 
|
| [Rsdoctor](https://github.com/web-infra-dev/rsdoctor) | Build analyzer | 
|
| [Rstest](https://github.com/web-infra-dev/rstest) | Testing framework | 
|
| [Rslint](https://github.com/web-infra-dev/rslint) | Linter | 
|
## Links
- [awesome-rstack](https://github.com/rstackjs/awesome-rstack): A curated list of awesome things related to Rstack.
- [agent-skills](https://github.com/rstackjs/agent-skills): A collection of Agent Skills for Rstack.
- [rstack-examples](https://github.com/rstackjs/rstack-examples): Examples showcasing Rstack tools.
- [storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild): Storybook builder powered by Rsbuild.
- [rsbuild-plugin-template](https://github.com/rstackjs/rsbuild-plugin-template): Use this template to create your own Rsbuild plugin.
- [rstack-design-resources](https://github.com/rstackjs/rstack-design-resources): Design resources for Rstack.
## Community
Come and chat with us on [Discord](https://discord.gg/XsaKEEk4mW)! The Rstack team and users are active there, and we're always looking for contributions.
## Online example
Try Rslib online with the [StackBlitz example](https://stackblitz.com/~/github.com/rstackjs/rslib-stackblitz-example).
## Next steps
Please read [Quick start](/guide/start/quick-start.md) to start using Rslib.
---
url: /guide/start/quick-start.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Quick start
## Environment preparation
Rslib supports using [Node.js](https://nodejs.org/), [Deno](https://deno.com/), or [Bun](https://bun.sh/) as the JavaScript runtime.
Use one of the following installation guides to set up a runtime:
- [Install Node.js](https://nodejs.org/en/download)
- [Install Bun](https://bun.com/docs/installation)
- [Install Deno](https://docs.deno.com/runtime/getting_started/installation/)
:::tip Version requirements
Rslib v1 requires Node.js version 20.19+, 22.12+.
:::
## Creating an Rslib project
Use [`create-rslib`](https://www.npmjs.com/package/create-rslib) to create a new Rslib project. Run the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
```sh [deno]
deno init --npm rslib@latest
```
Follow the prompts step by step. During project creation, you can choose a template, language, optional tools, and optional skills.
All templates include [Rstest](https://rstest.rs/) by default for testing.
By default, the scaffold initializes a Git repository in the generated project. Pass `--no-git` to skip Git initialization.
After creating the project, do the following:
- Run `npm install` (or your package manager's install command) to install dependencies.
- Run `npm run dev` to start watch mode and begin development.
### Templates
When creating a project, you can choose from the following templates provided by `create-rslib`:
| Template | Description |
| --------------- | ------------------------ |
| Node.js package | Node.js package |
| React | React component library |
| Vue | Vue component library |
| Svelte | Svelte component library |
| Solid | Solid component library |
### Optional tools
`create-rslib` can help you set up the following commonly used tools. Use the arrow keys to navigate and the space bar to select. Press Enter without selecting anything to skip these tools.
| Tool | Use |
| --------------------------------------------------------- | --------------------------------------------------------- |
| [ESLint](https://eslint.org/) | Linting |
| [Rslint](https://rslint.rs/) | Linting |
| [Prettier](https://prettier.io/) | Formatting |
| [Biome](https://biomejs.dev/) | Linting and formatting |
| [Rspress](https://rspress.rs/) | Component documentation, React + TypeScript template |
| [Storybook](https://storybook.js.org/) | Component development and preview, React or Vue templates |
| [React Compiler](/guide/solution/react.md#react-compiler) | Optimizing React components, React template only |
### Optional skills
`create-rslib` can install optional skills for coding agents that support Skills. In interactive mode, your selections in “Optional tools” affect the available skill options. The currently available skills are:
| Name | Condition |
| ------------------------------------------------------------------------------------------------------- | ---------------- |
| [rslib-best-practices](https://github.com/rstackjs/agent-skills#rslib-best-practices) | Default |
| [rstest-best-practices](https://github.com/rstackjs/agent-skills#rstest-best-practices) | Default |
| [rspress-custom-theme](https://github.com/rstackjs/agent-skills#rspress-custom-theme) | Choose `Rspress` |
| [rspress-description-generator](https://github.com/rstackjs/agent-skills#rspress-description-generator) | Choose `Rspress` |
Use the arrow keys to navigate and the space bar to select. Press Enter without selecting anything to skip.
```text
◆ Select optional skills (Use to select, to continue)
│ ◻ Rslib - best practices
│ ◻ Rstest - best practices
```
For more details about Agent Skills and other AI-related capabilities, see [AI](/guide/start/ai.md).
### Current directory
To create a project in the current directory, set the target folder to `.`:
```text
◆ Create Rslib Project
│
◇ Project name or path
│ .
│
◇ "." is not empty, please choose:
│ Continue and override files
```
### Non-interactive mode
[create-rslib](https://www.npmjs.com/package/create-rslib) supports a non-interactive mode via command-line options. This mode skips prompts and creates the project directly, which is useful for scripts, CI, and automation.
For example, the following command creates a React project in the `my-project` directory:
```bash
npx -y create-rslib@latest my-project --template react
# Using abbreviations
npx -y create-rslib@latest my-project -t react
# Specify multiple tools
npx -y create-rslib@latest my-project -t react --tools storybook,biome
# Install an optional skill for coding agents
npx -y create-rslib@latest my-project -t react --skill rslib-best-practices
```
All CLI flags supported by `create-rslib`:
```text
Usage: create-rslib [dir] [options]
Options:
-h, --help display help for command
-d, --dir create project in specified directory
-t, --template specify the template to use
--no-git skip Git repository initialization
--tools add additional tools, comma separated
--skill add optional skills, comma separated
--override override files in target directory
--packageName specify the package name
Available templates:
node-js, node-ts, react-js, react-ts, vue-js, vue-ts, svelte-js, svelte-ts, solid-js, solid-ts
Optional tools:
react-compiler, eslint, rslint, biome, prettier, rspress, storybook
Optional skills:
rslib-best-practices, rstest-best-practices, rspress-custom-theme, rspress-description-generator
```
## Migrate from existing projects
To migrate from an existing project to Rslib, refer to the following guides:
- [Migrating from tsup](/guide/migration/tsup.md)
- [Migrating from tsc](/guide/migration/tsc.md)
### Other projects
For other types of projects, you can manually install the [@rslib/core](https://www.npmjs.com/package/@rslib/core) package:
```sh [npm]
npm add @rslib/core -D
```
```sh [yarn]
yarn add @rslib/core -D
```
```sh [pnpm]
pnpm add @rslib/core -D
```
```sh [bun]
bun add @rslib/core -D
```
```sh [deno]
deno add npm:@rslib/core -D
```
Then refer to the guide and documentation to enable the features you need:
- See [CLI](/guide/basic/cli.md) to learn about available CLI commands.
- See [Configure Rslib](/guide/basic/configure-rslib.md) to configure Rslib.
---
url: /guide/start/glossary.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Glossary
## ESM
ESM stands for [ECMAScript modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules), which is a modern module system introduced in ES2015 that allows JavaScript code to be organized into reusable, self-contained modules. ESM is now the standard for both [browser](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [Node.js](https://nodejs.org/api/esm.html) environments, replacing older module systems like [CommonJS (CJS)](https://nodejs.org/api/modules.html) and [AMD](https://requirejs.org/docs/whyamd.html).
## CJS
CJS stands for [CommonJS modules](https://nodejs.org/api/modules.html#modules-commonjs-modules), which is a module system used in JavaScript, particularly in server-side environments like Node.js. It was created to allow JavaScript to be used outside of the browser by providing a way to manage modules and dependencies.
## UMD
UMD stands for [Universal Module Definition](https://github.com/umdjs/umd), a pattern for writing JavaScript modules that can work universally across different environments, such as both the browser and Node.js. Its primary goal is to ensure compatibility with the most popular module systems, including AMD (Asynchronous Module Definition), CommonJS (CJS), and browser globals.
## Bundleless
Bundleless means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of bundleless build can also be understood as the process of code transformation of source files only.
## Module Federation
Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends).
See [Module Federation](https://rsbuild.rs/guide/advanced/module-federation) for more details.
## More
See more glossary in [Rsbuild - Glossary](https://rsbuild.rs/guide/start/glossary) and [Rspack - Glossary](https://rspack.rs/misc/glossary).
---
url: /guide/start/npm-packages.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Packages
This document showcases all the npm package information maintained by Rslib team.
## @rslib/core
Rslib core package that provides CLI commands and build capabilities based on Rsbuild.
- [npm](https://npmjs.com/package/@rslib/core)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/core)
## rsbuild-plugin-dts
Rsbuild plugin that supports emitting declaration files for TypeScript.
- [npm](https://npmjs.com/package/rsbuild-plugin-dts)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/plugin-dts)
## create-rslib
Used to create a new Rslib project.
- [npm](https://npmjs.com/package/create-rslib)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/create-rslib)
---
url: /guide/start/ai.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# AI
To help AI better understand Rslib's features, configuration, and best practices so it can provide more accurate assistance during day-to-day development and troubleshooting, Rslib provides the following capabilities:
- [Agent Skills](#agent-skills)
- [llms.txt](#llmstxt)
- [Markdown docs](#markdown-docs)
- [AGENTS.md](#agentsmd)
## Agent Skills
Agent Skills are domain-specific knowledge packs that can be installed into Agents, enabling them to give more accurate and professional suggestions or perform actions in specific scenarios.
In the [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) repository, there are many skills for the Rstack ecosystem. The skills related to Rslib include:
- [rslib-best-practices](https://github.com/rstackjs/agent-skills#rslib-best-practices): Best practices for Rslib.
- [rslib-modern-package](https://github.com/rstackjs/agent-skills#rslib-modern-package): Recommendations for designing and publishing modern JavaScript packages.
- [migrate-to-rslib](https://github.com/rstackjs/agent-skills#migrate-to-rslib): Migrate existing tsc or tsup projects to Rslib.
In Coding Agents that support skills, you can use the [skills](https://www.npmjs.com/package/skills) package to install a specific skill with the following command:
```sh [npx]
npx skills add rstackjs/agent-skills --skill migrate-to-rslib
```
```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```
```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```
```sh [bunx]
bunx skills add rstackjs/agent-skills --skill migrate-to-rslib
```
```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill migrate-to-rslib
```
After installation, simply use natural language prompts to trigger the skill, for example:
```
Help me migrate this tsc project to Rslib
```
## llms.txt
[llms.txt](https://llmstxt.org/) is a standard that helps LLMs discover and use project documentation. Rslib follows this standard and publishes the following two files:
- [llms.txt](https://rslib.rs/llms.txt): A structured index file containing the titles, links, and brief descriptions of all documentation pages.
```
https://rslib.rs/llms.txt
```
- [llms-full.txt](https://rslib.rs/llms-full.txt): A full-content file that concatenates the complete content of every documentation page into a single file.
```
https://rslib.rs/llms-full.txt
```
You can choose the file that best fits your use case:
- `llms.txt` is smaller and consumes fewer tokens, making it suitable for AI to fetch specific pages on demand.
- `llms-full.txt` contains the complete documentation content, so AI doesn't need to follow individual links — ideal when you need AI to have a comprehensive understanding of Rslib, though it consumes more tokens and is best used with AI tools that support large context windows.
## Markdown docs
Every Rslib documentation page has a corresponding `.md` plain-text version that can be provided directly to AI. On any doc page, you can click “Copy Markdown” or “Copy Markdown Link” in the page outline to get the Markdown content or link.
```
https://rslib.rs/guide/start/index.md
```
Providing the Markdown link or content allows AI to focus on a specific chapter, which is useful for targeted troubleshooting or looking up a particular topic.
## AGENTS.md
When you create a new project with [create-rslib](https://www.npmjs.com/package/create-rslib), the generated project includes an `AGENTS.md` file. This file follows the [AGENTS.md](https://agents.md/) specification and provides key project information to Agents.
Example `AGENTS.md` content:
```markdown wrapCode
# AGENTS.md
You are an expert in JavaScript, Rspack, Rsbuild, Rslib, and library development. You write maintainable, performant, and accessible code.
## Commands
- `npm run build` - Build the library for production
- `npm run dev` - Turn on watch mode, watch for changes and rebuild the library
## Docs
- Rslib: https://rslib.rs/llms.txt
- Rsbuild: https://rsbuild.rs/llms.txt
- Rspack: https://rspack.rs/llms.txt
```
You can also customize it for your project, adding more details about the project structure, overall architecture, and other relevant information so Agents can better understand your project.
---
url: /guide/solution/index.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Overview
In this chapter, we will introduce how to use Rslib to development libraries for browser and Node.js. We will also cover how to create libraries for different UI frameworks.
## Browser target
When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format.md#esm--cjs) and [CJS](/guide/basic/output-format.md#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format.md#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation.md) formats for dynamic loading by other applications. Configure [Browserslist](https://rsbuild.rs/guide/advanced/browserslist) according to the target browser support to determine the downgrade syntax of the output, or add a [polyfill](/guide/advanced/output-compatibility.md) for API compatibility.
When publishing to npm, you can choose not to [minify](/config/rsbuild/output.md#outputminify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output.md#outputsourcemap) to enhance the debugging experience for users of your library. For styling, you can use CSS, or CSS pre-processors like Sass, Less, or Stylus, or apply PostCSS for CSS post-processing. Tools like Tailwind CSS can also help in building your styles. Using CSS Modules to create CSS modules is another option.
In terms of resource management, Rslib handles static assets used in your code, such as SVG and PNG files, and supports compiling [Web Workers](/guide/advanced/web-workers.md) for ESM libraries. You can also build a component library of [React](/guide/solution/react.md), [Preact](https://github.com/rstackjs/rstack-examples/tree/main/rslib/preact), or other frameworks, and use [Storybook](/guide/advanced/storybook.md) for UI component development and testing.
Refer to the solutions in this chapter to learn how to use Rslib to develop browser libraries for different frameworks.
## Node.js target
Rslib set [target](/config/rsbuild/output.md#outputtarget) to `"node"` by default to development libraries for Node.js.
You can create a [pure ESM](/guide/basic/output-format.md#esm--cjs) package or a [dual package](/guide/basic/output-format.md#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims.md) for compatibility and `__dirname` and `__filename` got optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps.md).
---
url: /guide/solution/nodejs.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Node.js
In this document, you will learn how to build a Node.js library using Rslib. You can check out Node.js related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).
## Create Node.js project
You can use `create-rslib` to create a project with Rslib + Node.js. Just execute the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
Then select `Node.js` when prompted to "Select template".
## Use Rslib in an existing project
Rslib offers seamless support for Node.js projects, allowing you to build them effortlessly with minimal configuration.
For example, in `rslib.config.ts`:
```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
export default defineConfig({});
```
## Target for Node.js
Rslib sets [target](/config/rsbuild/output.md#outputtarget) to `"node"` by default, which is different from the default target of Rsbuild.
When target is set to `"node"`, Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output.md#outputtarget) will exclude built-in Node.js modules, and [shims](/config/lib/shims.md) will add a shim for `import.meta.url` in CJS output by default.
### Externals
All Node.js [built-in modules](https://nodejs.org/docs/latest/api/) are externalized by default.
### Shims
- `global`: leave it as it is, while it's recommended to use [globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) instead.
- `__filename`: When outputting in ESM format, replace `__filename` with the result of `fileURLToPath(import.meta.url)`.
- `__dirname`: When outputting in ESM format, replace `__dirname` with the result of `dirname(fileURLToPath(import.meta.url))`.
---
url: /guide/solution/react.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# React
In this document, you will learn how to build a React component library with Rslib. You can check out React related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).
## Create React project
You can use `create-rslib` to create a project with Rslib + React. Just execute the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
Then select `React` when prompted to "Select template".
## Use Rslib in an existing project
To develop a React library, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild.
To compile React (JSX and TSX), you need to register the Rsbuild [React Plugin](https://rsbuild.rs/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds.
For example, register in `rslib.config.ts`:
```ts title="rslib.config.ts" twoslash
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react'; // [!code highlight]
export default defineConfig({
lib: [
// ...
],
// [!code highlight:4]
output: {
target: 'web',
},
plugins: [pluginReact(/** options here */)],
});
```
## JSX transform
- **Type:** `'automatic' | 'classic' | 'preserve'`
- **Default:** `'automatic'`
React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in version 17. This new transform removes the need to import `React` when using JSX.
By default, Rslib uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher and the `peerDependencies` should be specified as `"react": ">=16.14.0"`.
To change the JSX transform, you can set the [swcReactOptions](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime) option in `@rsbuild/plugin-react`.
For example, to use the classic runtime:
```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
lib: [
// ...
],
output: {
target: 'web',
},
plugins: [
pluginReact({
// [!code highlight:3]
swcReactOptions: {
runtime: 'classic',
},
}),
],
});
```
When you need to keep native JSX in the build output, you can set the runtime to `'preserve'` to leave JSX syntax unchanged without transforming it, which is useful for subsequent processing by other bundlers.
::: warning
When using `runtime: 'preserve'`, you must set `bundle: false` to enable [bundleless mode](/guide/basic/output-structure.md#bundle--bundleless) to keep files unbundled.
:::
To emit `.jsx` files, you can configure the JS filename template through [output.filename](/config/rsbuild/output.md#outputfilename) option:
```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
lib: [
{
bundle: false,
format: 'esm',
// [!code highlight:5]
output: {
filename: {
js: '[name].jsx',
},
},
},
],
plugins: [
pluginReact({
swcReactOptions: {
runtime: 'preserve',
},
}),
],
});
```
## JSX import source
- **Type**: `string`
- **Default**: `'react'`
When `runtime` is set to `'automatic'`, you can specify the import path of the JSX transform through `importSource`.
For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:
```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
lib: [
// ...
],
output: {
target: 'web',
},
plugins: [
pluginReact({
// [!code highlight:3]
swcReactOptions: {
importSource: '@emotion/react',
},
}),
],
});
```
## React Compiler
React Compiler is a build-time tool that automatically optimizes your React app. It works with plain JavaScript, and understands the Rules of React, so you don't need to rewrite any code to use it.
Before using React Compiler, we recommend reading the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand its functionality, current state, and usage.
### How to use
Steps to use React Compiler in Rslib:
1. Upgrade `react` and `react-dom` to v19. If you can't upgrade, install the [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) package to run the compiled code on earlier versions.
2. Enable React Compiler through the `reactCompiler` option of `@rsbuild/plugin-react`:
```ts title="rslib.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
plugins: [
pluginReact({
reactCompiler: true,
}),
],
});
```
This uses the Rust version of React Compiler integrated in `builtin:swc-loader`, which is around **7-13x faster** than the Babel version.
> You can also refer to the [example project](https://github.com/rstackjs/rstack-examples/tree/main/rslib/react-compiler).
### Configuration
Pass a config object to customize the React Compiler behavior. For all available options, refer to the [`reactCompiler`](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) option of `@rsbuild/plugin-react`.
```ts title="rslib.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
plugins: [
pluginReact({
reactCompiler: {
compilationMode: 'annotation',
},
}),
],
});
```
For React 17 and 18 projects, install [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) and specify the `target`:
```ts title="rslib.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
plugins: [
pluginReact({
reactCompiler: {
target: '18', // '17' | '18' | '19'
},
}),
],
});
```
The `reactCompiler` options are aligned with the React Compiler configuration. For more options, refer to the official [React Compiler configuration documentation](https://react.dev/reference/react-compiler/configuration).
### Using Babel
You can also use the Babel plugin published by React Compiler. This is useful if you need Babel-specific integration or options that are not yet available in the SWC transform.
Install [@rsbuild/plugin-babel](https://rsbuild.rs/plugins/list/plugin-babel) and [babel-plugin-react-compiler](https://npmjs.com/package/babel-plugin-react-compiler), then register the Babel plugin in your Rslib config file:
```ts title="rslib.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
export default defineConfig({
plugins: [
pluginReact(),
pluginBabel({
include: /\.[jt]sx?$/,
exclude: [/[\\/]node_modules[\\/]/],
babelLoaderOptions(opts) {
opts.plugins ??= [];
opts.plugins.unshift('babel-plugin-react-compiler');
},
}),
],
});
```
## SVGR
Read [SVGR](/guide/advanced/svgr-files.md) for more details.
## Further reading
- [Rsbuild React Plugin](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime)
- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact)
---
url: /guide/solution/reactlynx.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# ReactLynx
In this document, you will learn how to build a [ReactLynx](https://lynxjs.org/react/introduction) component library for Lynx applications with Rslib. You can check out ReactLynx related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib/reactlynx-basic).
## Create a ReactLynx project
You can use [`@lynx-js/create-lynx`](https://www.npmjs.com/package/@lynx-js/create-lynx) to create a ReactLynx component library with Rslib:
```sh [npm]
npm create @lynx-js/lynx@latest
```
```sh [yarn]
yarn create @lynx-js/lynx
```
```sh [pnpm]
pnpm create @lynx-js/lynx@latest
```
```sh [bun]
bun create @lynx-js/lynx@latest
```
```sh [deno]
deno init --npm @lynx-js/lynx@latest
```
Then select `Rslib` when prompted to "Select build tool", followed by TypeScript or JavaScript. You can also specify the Rslib template directly:
```sh [npm]
npm create @lynx-js/lynx@latest my-lib -- --template rslib-react-ts
```
```sh [yarn]
yarn create @lynx-js/lynx my-lib --template rslib-react-ts
```
```sh [pnpm]
pnpm create @lynx-js/lynx@latest my-lib --template rslib-react-ts
```
```sh [bun]
bun create @lynx-js/lynx@latest my-lib --template rslib-react-ts
```
```sh [deno]
deno init --npm @lynx-js/lynx@latest my-lib --template rslib-react-ts
```
## Use Rslib in an existing project
To develop a ReactLynx library, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild.
Additionally, ReactLynx component libraries typically need to preserve JSX syntax in the build output so that the application's ReactLynx compiler can process it according to the target environment and build configuration. You can register the Rsbuild [React Plugin](https://rsbuild.rs/plugins/list/plugin-react), set `runtime` to `'preserve'` through [swcReactOptions](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime), and set [bundle](/config/lib/bundle.md) to `false` to enable bundleless builds. Also, set `js` to `'[name].jsx'` in [output.filename](/config/rsbuild/output.md#outputfilename) to emit `.jsx` files.
For example, configure `rslib.config.ts` as follows:
```ts title="rslib.config.ts" twoslash
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react'; // [!code highlight]
export default defineConfig({
bundle: false, // [!code highlight]
// [!code highlight:6]
output: {
target: 'web',
filename: {
js: '[name].jsx',
},
},
plugins: [
pluginReact({
// [!code highlight:3]
swcReactOptions: {
runtime: 'preserve',
},
}),
],
});
```
## TypeScript
For ReactLynx projects using TypeScript, set `"jsx": "preserve"` and `"jsxImportSource": "@lynx-js/react"` in your `tsconfig.json`, and add `@lynx-js/types` to `types`:
```json title="tsconfig.json"
{
"compilerOptions": {
// [!code highlight:3]
"jsx": "preserve",
"jsxImportSource": "@lynx-js/react",
"types": ["@lynx-js/types", "@rslib/core/types"]
}
}
```
Set [dts](/config/lib/dts.md) to `true` in `rslib.config.ts` to generate the library's type declarations.
## Output
Configure the `.jsx` entry and type declaration entry in `package.json`, and declare ReactLynx and its type dependencies as peer dependencies:
```json title="package.json"
{
"name": "reactlynx-scroll-list",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts", // [!code ++]
"default": "./dist/index.jsx" // [!code ++]
}
},
"types": "./dist/index.d.ts", // [!code ++]
"files": ["dist"],
"peerDependencies": {
"@lynx-js/react": ">=0.100.0", // [!code ++]
"@lynx-js/types": ">=4", // [!code ++]
"@types/react": ">=19" // [!code ++]
}
}
```
## Testing
You can use Rstest to test ReactLynx components. First, install the dependencies needed for testing:
```sh [npm]
npm add @rstest/core @rstest/adapter-rslib @lynx-js/react-rsbuild-plugin @testing-library/dom @testing-library/jest-dom happy-dom -D
```
```sh [yarn]
yarn add @rstest/core @rstest/adapter-rslib @lynx-js/react-rsbuild-plugin @testing-library/dom @testing-library/jest-dom happy-dom -D
```
```sh [pnpm]
pnpm add @rstest/core @rstest/adapter-rslib @lynx-js/react-rsbuild-plugin @testing-library/dom @testing-library/jest-dom happy-dom -D
```
```sh [bun]
bun add @rstest/core @rstest/adapter-rslib @lynx-js/react-rsbuild-plugin @testing-library/dom @testing-library/jest-dom happy-dom -D
```
```sh [deno]
deno add npm:@rstest/core npm:@rstest/adapter-rslib npm:@lynx-js/react-rsbuild-plugin npm:@testing-library/dom npm:@testing-library/jest-dom npm:happy-dom -D
```
Use the `withRslibConfig` function from `@rstest/adapter-rslib` to reuse your Rslib configuration. See [Use Rstest](/guide/advanced/rstest.md) for details.
Also, use the `withDefaultConfig` function provided by `@lynx-js/react` to load the [ReactLynx test preset](https://lynxjs.org/api/reactlynx-testing-library/#rstest), and register the `pluginReactLynx` plugin from `@lynx-js/react-rsbuild-plugin` to compile JSX:
```ts title="rstest.config.ts"
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'; // [!code ++]
import { withDefaultConfig } from '@lynx-js/react/testing-library/rstest-config'; // [!code ++]
import { withRslibConfig } from '@rstest/adapter-rslib';
import { defineConfig } from '@rstest/core';
export default defineConfig({
extends: [withDefaultConfig(), withRslibConfig()], // [!code ++]
plugins: [pluginReactLynx()], // [!code ++]
});
```
Once configured, import APIs such as `render`, `screen`, and `fireEvent` from `@lynx-js/react/testing-library` to test component rendering and interactions.
See the [ReactLynx testing guide](https://lynxjs.org/react/reactlynx-testing-library.html) for usage details. You can find a complete component testing project in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib/reactlynx-rstest).
## Use the component library
### Use in an application
In a Lynx application, you can use a ReactLynx component library by importing it as a package or loading it as an External Bundle.
#### Import from a package
The component library built and published with the configuration above preserves JSX. After installing it in a Lynx application, you can import and use its components directly, with their JSX processed by the application's ReactLynx compiler. For example, use the `ScrollList` exported by the library:
```tsx title="src/App.tsx"
import { ScrollList } from 'reactlynx-scroll-list';
export function App() {
return ;
}
```
#### Load an external bundle
Lynx applications can also load an External Bundle on demand at runtime. Its JSX has already been compiled during the bundle build. When creating the library, you can select the optional `External Bundle` tool or enable it with `--tools external-bundle` in the initialization command:
```sh [npm]
npm create @lynx-js/lynx@latest my-lib -- --template rslib-react-ts --tools external-bundle
```
```sh [yarn]
yarn create @lynx-js/lynx my-lib --template rslib-react-ts --tools external-bundle
```
```sh [pnpm]
pnpm create @lynx-js/lynx@latest my-lib --template rslib-react-ts --tools external-bundle
```
```sh [bun]
bun create @lynx-js/lynx@latest my-lib --template rslib-react-ts --tools external-bundle
```
```sh [deno]
deno init --npm @lynx-js/lynx@latest my-lib --template rslib-react-ts --tools external-bundle
```
The generated project includes `rslib.external-bundle.config.*` and a `build:external-bundle` script. Run the following command to compile the library into `dist-external-bundle/.lynx.bundle`:
```sh [npm]
npm run build:external-bundle
```
```sh [yarn]
yarn run build:external-bundle
```
```sh [pnpm]
pnpm run build:external-bundle
```
```sh [bun]
bun run build:external-bundle
```
```sh [deno]
deno run build:external-bundle
```
See the [Lynx External Bundle guide](https://lynxjs.org/rspeedy/external-bundle.html) for loading and configuration details.
### Use in a component library
You can use existing shared components in your library and preserve JSX for the application to compile. Distributing the package that provides those components as a dependency is recommended. If you need to publish its code with your library, copy output that is ready to use, or rebuild it when its code, styles, or internal imports need processing.
::: tip Type declarations
When publishing dependency code with your library by building or copying it, consumers still need to install the dependency if your `.d.ts` files reference its types. Use [dts.bundle.bundledPackages](/config/lib/dts.md#dtsbundlebundledpackages) to bundle those type declarations as well, for example by setting it to `['reactlynx-scroll-list']`.
:::
#### Distribute as a dependency (recommended)
Declare the library that provides the shared components in `dependencies` or `peerDependencies`. Rslib marks these dependencies as [external](/guide/advanced/third-party-deps.md#default-handling-of-third-party-dependencies) by default, preserving their package imports.
When consumers install your library, their package manager installs or reuses packages according to the declared dependencies. The application build then loads these libraries through their package imports and compiles their JSX together.
#### Rebuild dependency output
If you need to compile the dependency's code or styles, or change its internal imports, use Rslib to build your library and the dependency separately, and use [output.externals](/config/rsbuild/output.md#outputexternals) to rewrite imports.
Consider a component library that includes a scroll list adapted from `reactlynx-scroll-list` and other components you write. The configuration has three builds, each identified by an [id](/config/lib/id.md):
- `components`: builds the other components you write in bundleless mode, handling component code that needs to preserve JSX.
- `bundled-components`: bundles the scroll list entry and the local TS/JS modules it imports, which can adjust exports or include other TS/JS logic. It uses `output.externals` to reference the dependency output.
- `vendor`: rebuilds the output of `reactlynx-scroll-list`, preserving JSX and emitting files to `dist/vendor/reactlynx-scroll-list`.
In this example, only `src/scroll-list/index.ts` imports `reactlynx-scroll-list`. Other components reference this entry through local imports:
```ts title="src/scroll-list/index.ts"
export { ScrollList } from 'reactlynx-scroll-list';
```
Adjust [outBase](/config/lib/out-base.md) and the entry to match the dependency's actual output, including the code, styles, and static assets to process:
```ts title="rslib.config.ts"
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
const scrollListDir = dirname(
fileURLToPath(import.meta.resolve('reactlynx-scroll-list')),
);
const reactPlugin = pluginReact({
swcReactOptions: {
runtime: 'preserve',
},
});
export default defineConfig({
lib: [
{
id: 'components',
bundle: false, // [!code ++]
dts: true,
source: {
entry: {
index: [
'./src/**/*',
'!./src/scroll-list/**', // [!code ++]
],
},
},
plugins: [reactPlugin],
},
{
id: 'bundled-components',
source: {
entry: {
'scroll-list/index': './src/scroll-list/index.ts', // [!code ++]
},
},
output: {
externals: {
'reactlynx-scroll-list': '../vendor/reactlynx-scroll-list/index.jsx', // [!code ++]
},
},
},
{
id: 'vendor',
bundle: false, // [!code ++]
outBase: scrollListDir, // [!code ++]
source: {
entry: {
index: `${scrollListDir}/**/*.{js,jsx,css,svg}`, // [!code ++]
},
},
output: {
distPath: './dist/vendor/reactlynx-scroll-list', // [!code ++]
},
plugins: [reactPlugin],
},
],
output: {
target: 'web',
filename: {
js: '[name].jsx',
},
},
});
```
The top-level `output.filename` setting gives all builds a consistent `.jsx` extension for their code output. The generated `dist/scroll-list/index.jsx` imports `dist/vendor/reactlynx-scroll-list/index.jsx`, so include the entire `dist` directory when publishing your package.
If `reactlynx-scroll-list` imports other component libraries that also need to be distributed with your package, add builds for those packages. In the `vendor` build, use `output.externals` to rewrite their package imports to the paths of their output files.
#### Copy dependency output directly
If the dependency's output is ready to use and its internal imports need no changes, copy the complete output with [output.copy](/config/rsbuild/output.md#outputcopy).
The following configuration builds the library source in bundleless mode to preserve JSX and copies the dependency's output. As above, only `src/scroll-list/index.ts` imports the dependency, and the path in `output.externals` is relative to the generated `dist/scroll-list/index.jsx`:
```ts title="rslib.config.ts"
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';
const scrollListDir = dirname(
fileURLToPath(import.meta.resolve('reactlynx-scroll-list')),
);
export default defineConfig({
bundle: false,
dts: true,
output: {
target: 'web',
filename: {
js: '[name].jsx',
},
externals: {
'reactlynx-scroll-list': '../vendor/reactlynx-scroll-list/index.jsx', // [!code ++]
},
copy: [
{
from: scrollListDir, // [!code ++]
to: 'vendor/reactlynx-scroll-list', // [!code ++]
},
],
},
plugins: [
pluginReact({
swcReactOptions: {
runtime: 'preserve',
},
}),
],
});
```
---
url: /guide/solution/vue.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Vue
In this document, you will learn how to build a Vue component library using Rslib. You can check out Vue related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).
::: note
1. Only Vue 3 is supported, Vue 2 is not supported.
2. Vue's declaration files are generated by [vue-tsc](https://www.npmjs.com/package/vue-tsc), so [lib.dts](/config/lib/dts.md) / [lib.redirect.dts](/config/lib/redirect.md#redirectdts) / [lib.banner.dts](/config/lib/banner.md#bannerdts) / [lib.footer.dts](/config/lib/footer.md#footerdts) are not effective in Vue projects.
:::
## Create Vue project
You can use `create-rslib` to create a project with Rslib + Vue. Just execute the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
Then select `Vue` when prompted to "Select template".
## Use Rslib in an existing project
For developing Vue components, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets `target` to `"node"` by default, which is different from Rsbuild's default target value.
To compile Vue (.vue single-file components), you need to register the [@rsbuild/plugin-vue](https://rsbuild.rs/plugins/list/plugin-vue) plugin. This plugin will automatically add the necessary configurations for Vue build.
For example, register in `rslib.config.ts`:
```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginVue } from '@rsbuild/plugin-vue'; // [!code highlight]
export default defineConfig({
lib: [
// ...
],
// [!code highlight:4]
output: {
target: 'web',
},
plugins: [pluginVue(/** options here */)],
});
```
For more configuration options, please refer to the [@rsbuild/plugin-vue documentation](https://rsbuild.rs/plugins/list/plugin-vue).
---
url: /guide/solution/svelte.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Svelte
In this document, you will learn how to build a Svelte component library using Rslib. You can check out Svelte related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).
## Create Svelte project
You can use `create-rslib` to create a project with Rslib + Svelte. Just execute the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
Then select `Svelte` when prompted to "Select template".
## Use Rslib in an existing project
For developing Svelte components, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets `target` to `"node"` by default, which is different from Rsbuild's default target value.
To compile Svelte (`.svelte` files), you need to register the [@rsbuild/plugin-svelte](https://rsbuild.rs/plugins/list/plugin-svelte) plugin. This plugin integrates [svelte-loader](https://github.com/sveltejs/svelte-loader) internally and will automatically add the necessary configurations for Svelte build.
For example, register in `rslib.config.ts`:
```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginSvelte } from '@rsbuild/plugin-svelte'; // [!code highlight]
export default defineConfig({
lib: [
// ...
],
// [!code highlight:4]
output: {
target: 'web',
},
plugins: [pluginSvelte(/** options here */)],
});
```
For more configuration options, refer to the [@rsbuild/plugin-svelte documentation](https://rsbuild.rs/plugins/list/plugin-svelte).
## Declaration files
::: note
Svelte declaration files are generated by [`svelte2tsx`](https://www.npmjs.com/package/svelte2tsx), so [lib.dts](/config/lib/dts.md) / [lib.redirect.dts](/config/lib/redirect.md#redirectdts) / [lib.banner.dts](/config/lib/banner.md#bannerdts) / [lib.footer.dts](/config/lib/footer.md#footerdts) are not effective in Svelte projects.
:::
Rslib provides a plugin example for generating types in Svelte projects: [svelteDtsPlugin](https://github.com/web-infra-dev/rslib/blob/main/packages/create-rslib/template-svelte-ts/scripts/rslib-plugin-svelte-dts.ts). The plugin calls the `emitDts` method provided by [svelte2tsx](https://www.npmjs.com/package/svelte2tsx) after build to generate declaration files for `.svelte` files.
If you create a Svelte TypeScript project with `create-rslib`, this plugin is already included in the template.
For an existing project, you can use it like this:
```ts title="rslib.config.ts"
import { svelteDtsPlugin } from './scripts/rslib-plugin-svelte-dts';
export default {
plugins: [svelteDtsPlugin()],
};
```
`svelteDtsPlugin` passes the following options through to the [svelte2tsx](https://www.npmjs.com/package/svelte2tsx) [emitDts](https://github.com/sveltejs/language-tools/blob/master/packages/svelte2tsx/src/emitDts.ts) config:
- `declarationDir`: The output directory for declaration files. Defaults to `./dist`.
- `libRoot`: The source directory to emit declaration files for. Defaults to `./src`.
- `tsconfig`: The tsconfig path used for declaration generation. Defaults to [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath).
- `svelteShimsPath`: The path to the svelte2tsx shims type file. Defaults to `svelte2tsx/svelte-shims-v4.d.ts`.
If you need type checking, install the [svelte-check](https://www.npmjs.com/package/svelte-check) npm package and add a `check` command to `package.json`:
```json title="package.json"
{
"scripts": {
"check": "svelte-check"
},
"devDependencies": {
"svelte-check": "^4.7.6"
}
}
```
---
url: /guide/solution/solid.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# Solid
In this document, you will learn how to build a Solid component library using Rslib. You can check out Solid related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).
## Create Solid project
You can use `create-rslib` to create a project with Rslib + Solid. Just execute the following command:
```sh [npm]
npm create rslib@latest
```
```sh [yarn]
yarn create rslib
```
```sh [pnpm]
pnpm create rslib@latest
```
```sh [bun]
bun create rslib@latest
```
Then select `Solid` when prompted to "Select template".
## Use Rslib in an existing project
To develop a Solid library, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default.
To compile Solid JSX, you need to register both the [@rsbuild/plugin-babel](https://rsbuild.rs/plugins/list/plugin-babel) and [@rsbuild/plugin-solid](https://rsbuild.rs/plugins/list/plugin-solid) plugins. The Solid plugin uses [`babel-preset-solid`](https://www.npmjs.com/package/babel-preset-solid) to transform JSX into Solid's runtime DOM expressions.
```json title="package.json"
{
"devDependencies": {
"@rsbuild/plugin-babel": "^2.0.0",
"@rsbuild/plugin-solid": "^1.2.2",
"solid-js": "^1.9.9"
},
"peerDependencies": {
"solid-js": "^1.8.0"
}
}
```
```ts title="rslib.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel'; // [!code highlight]
import { pluginSolid } from '@rsbuild/plugin-solid'; // [!code highlight]
import { defineConfig } from '@rslib/core';
export default defineConfig({
lib: [
{
bundle: false,
dts: true,
// [!code highlight:6]
plugins: [
pluginBabel({
include: /\.(?:jsx|tsx)$/,
}),
pluginSolid(),
],
},
],
// [!code highlight:3]
output: {
target: 'web',
},
});
```
## Output
Solid component libraries usually ship two types of outputs:
- **Pre-compiled output**: JSX has already been transformed by `babel-preset-solid` into Solid runtime calls, such as `template()` and `insert()`. Application projects that use this component library can import this output directly, without configuring Solid JSX compilation.
- **JSX source output**: the library build does not compile Solid JSX. Instead, it preserves the original JSX syntax and exposes it through the `"solid"` condition name in `package.json` for the application-side toolchain.
When an application project that uses this component library can compile Solid JSX (for example, an Rsbuild project with `@rsbuild/plugin-solid` installed), module resolution will hit the `"solid"` condition name, read the JSX source output, and recompile it for the application's runtime target: browser apps compile it into client-side DOM rendering code (`generate: 'dom'`), while SSR frameworks compile it into server-side rendering code (`generate: 'ssr'`). Application projects without Solid JSX compilation configured fall back to the pre-compiled `"default"` entry.
```ts title="rslib.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginSolid } from '@rsbuild/plugin-solid';
import { defineConfig } from '@rslib/core';
export default defineConfig({
lib: [
{
// Compile JSX into Solid runtime calls, such as template(), insert(), and delegateEvents().
dts: true,
plugins: [
pluginBabel({
include: /\.(?:jsx|tsx)$/,
}),
pluginSolid(),
],
},
{
// Preserve JSX syntax for the "solid" condition name.
output: {
filename: {
js: '[name].jsx',
},
},
tools: {
swc: {
detectSyntax: 'auto',
jsc: {
transform: {
react: {
// Keep JSX syntax in the output.
runtime: 'preserve',
},
},
},
},
rspack: {
module: {
parser: {
javascript: {
// Allow Rspack to parse preserved JSX.
jsx: true,
},
},
},
},
},
},
],
bundle: false,
output: {
target: 'web',
},
});
```
Then configure the `"exports"` field in `package.json`:
```json title="package.json"
{
// [!code highlight:7]
"exports": {
".": {
"types": "./dist/index.d.ts",
"solid": "./dist/index.jsx",
"default": "./dist/index.js"
}
}
}
```
## TypeScript
For Solid projects using TypeScript, set `"jsx": "preserve"` and `"jsxImportSource": "solid-js"` in your `tsconfig.json`:
```json title="tsconfig.json"
{
"compilerOptions": {
// [!code highlight:2]
"jsx": "preserve",
"jsxImportSource": "solid-js"
}
}
```
## SSR
Most Solid component libraries do not publish a separate SSR build by default. Instead, downstream frameworks resolve the `"solid"` condition name, get the preserved JSX output, and compile it for their own target.
If you intentionally need a pre-compiled SSR output, configure `pluginSolid` with the `solid.generate` option set to `'ssr'`:
```ts title="rslib.config.ts"
export default defineConfig({
lib: [
// ... existing compiled and source entries
// [!code highlight:21]
{
id: 'server',
bundle: false,
output: {
distPath: {
root: './dist/server',
},
},
plugins: [
pluginBabel({
include: /\.(?:jsx|tsx)$/,
}),
pluginSolid({
solid: {
generate: 'ssr',
hydratable: true,
},
}),
],
},
],
});
```
---
url: /guide/basic/cli.md
---
> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# CLI
Rslib comes with a lightweight CLI that includes commands such as [rslib](#rslib) and [rslib inspect](#rslib-inspect).
## All commands
To view all available CLI commands, run the following command in the project directory:
```bash
npx rslib -h
```
The output is shown below:
```bash
Usage:
$ rslib [command] [options]
Commands:
build build the library for production (default if no command is given)
inspect inspect the Rsbuild / Rspack configs of Rslib projects
mf-dev start Rsbuild dev server of Module Federation format
```
## Common flags
Rslib CLI provides several common flags that can be used with all commands:
| Flag | Description |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config ` | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rslib.md#specify-config-file) |
| `--config-loader ` | Set the config file loader (`auto` \| `jiti` \| `native`), see [Specify config loader](/guide/basic/configure-rslib.md#specify-config-loader) |
| `--env-dir ` | Specify the directory to load `.env` files, see [Rsbuild - Env directory](https://rsbuild.rs/guide/advanced/env-vars#env-directory) |
| `--env-mode ` | Specify the env mode to load the `.env.[mode]` file, see [Rsbuild - Env mode](https://rsbuild.rs/guide/advanced/env-vars#env-mode) |
| `-h, --help` | Display help for command |
| `--lib ` | Specify the library to run commands (repeatable, e.g. `--lib esm --lib cjs`), see [lib.id](/config/lib/id.md) to learn how to get or set the ID of the library |
| `--log-level ` | Set the log level (`info` \| `warn` \| `error` \| `silent`), see [logLevel](/config/rsbuild/log-level.md) |
| `--no-env` | Disable loading of `.env` files |
| `-r, --root ` | Specify the project root directory, can be an absolute path or a path relative to cwd |
## rslib
The `rslib` command will build the outputs for production in the `dist/` directory by default. `rslib build` is an alias for the `rslib` command.
```bash
Usage:
$ rslib
Options:
-w, --watch turn on watch mode, watch for changes and rebuild
--entry set entry file or pattern (repeatable)
--dist-path set output directory
--bundle enable bundle mode (use --no-bundle to disable)
--format specify the output format (esm | cjs | umd | mf | iife)
--syntax set build syntax target (repeatable)
--target set runtime target (web | node)
--dts emit declaration files (use --no-dts to disable)
--externals add package to externals (repeatable)
--minify minify output (use --no-minify to disable)
--clean clean output directory before build (use --no-clean to disable)
--auto-extension control automatic extension redirect (use --no-auto-extension to disable)
--auto-external control automatic dependency externalization (use --no-auto-external to disable)
--tsconfig use specific tsconfig (relative to project root)
```
:::note
If the [Rslib configuration file](/guide/basic/configure-rslib.md#configuration-file) is not present in your project, the CLI will automatically use the default configuration containing only a single [lib](/config/lib/index.md) and apply all build options from the command line. You can add a configuration file once you need a more complex configuration or want to build outputs in multiple formats.
:::
### Watch mode
Use `rslib --watch` or `rslib -w` to enable watch mode. Rslib watches for source file changes and automatically rebuilds when they change.
If you need to adjust the configuration based on whether watch mode is enabled, check `process.argv`:
```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
const isWatch = process.argv.some((arg) => arg === '--watch' || arg === '-w');
export default defineConfig({
source: {
alias: {
'@request': isWatch ? './src/request.dev.js' : './src/request.prod.js',
},
},
});
```
## rslib inspect
The `rslib inspect` command inspects a project's Rslib config and the corresponding Rsbuild and Rspack configs.
```bash
Usage:
$ rslib inspect
Options:
--mode set the build mode (development | production)
--output