# rslib-best-practices

Provides guidelines for building JavaScript and TypeScript libraries with Rslib. Useful when configuring outputs, declaration files, and dependency bundling.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1000 installs · ★ 97
- Author: rstackjs
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rslib-best-practices/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/rslib-best-practices

## What it does

The skill provides guidelines for configuring Rslib projects built on Rspack. It guides the model to use `rslib.config.ts` with `defineConfig` and prioritize Rslib-specific options under `lib.*`. Component libraries prefer bundleless output with `output.target` set to `'web'`. Utility packages for Node.js use bundled mode. It also enforces pure ESM with `"type": "module"` in `package.json` alongside strict mapping of the `exports` field to generated JavaScript and type files.

Dependency handling follows clear boundaries. Packages listed in `dependencies` and `peerDependencies` are externalized automatically during bundling, so bundled code belongs in `devDependencies`. Type definitions rely on `lib.dts`. To speed up type emission with the experimental `lib.dts.tsgo` flag, you must install `@typescript/native-preview` beforehand, because the feature will not run without it.

For troubleshooting, the instructions suggest running `rslib inspect` or setting `DEBUG=rsbuild`. Resolved configs should always be confirmed inside `dist/.rsbuild` rather than assumed. The rules also point to Rstest with `@rstest/adapter-rslib` for testing and Rspress for component documentation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rslib-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/rslib-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/rslib-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rslib-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/rslib-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rslib-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/rslib-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install rstackjs/agent-skills rslib-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/rslib-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rslib-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rslib-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/rslib-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add rstackjs/agent-skills --skill rslib-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rslib-best-practices/SKILL.md

## When to use it
- configure library builds inside `rslib.config.ts`
- map `exports` in `package.json` to actual build outputs and declaration files
- isolate external dependencies from bundled dependencies
- accelerate declaration file generation using experimental `tsgo`
- inspect resolved Rspack configurations with `rslib inspect`

## Example prompts
- Help me configure `rslib.config.ts` for a component library using bundleless mode.
- Verify that my `package.json` exports match the generated ESM files and declarations.
- Check why external dependencies are getting bundled into my Rslib build.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8347582f8c32f086.

BEGIN THIRD-PARTY FILE 8347582f8c32f086
```text
---
name: rslib-best-practices
description: Configure, review, or troubleshoot Rslib library builds, output formats, declarations, dependency handling, and integrations.
---

# Rslib best practices

Apply these rules when writing or reviewing Rslib library projects.

## Configuration

- Use `rslib.config.ts` and `defineConfig`
- Check Rslib-specific configurations first (e.g., `lib.*`), and also leverage Rsbuild configurations (e.g., `source.*`, `output.*`, `tools.*`) as needed
- For deep-level or advanced configuration needs, use `tools.rspack` or `tools.bundlerChain` to access Rspack's native configurations
- In TypeScript projects, prefer `tsconfig.json` path aliases

## CLI

- Use `rslib` to build
- Use `rslib --watch` to build in watch mode for local development
- Use `rslib inspect` to inspect final Rslib/Rsbuild/Rspack configs

## Output

- Prefer to build pure-ESM package with `"type": "module"` in `package.json`
- Prefer to use bundleless mode with `output.target` set to `'web'` when building component libraries
- Prefer to use bundle mode when building Node.js utility libraries
- Ensure `exports` field in `package.json` is correctly configured and matches the actual JavaScript output and declaration files output of different formats (ESM, CJS, etc.)

## Declaration files

- Prefer to enable declaration file generation with `lib.dts: true` or detailed configurations
- For faster type generation, enable `lib.dts.tsgo` experimental feature with `@typescript/native-preview` installed

## Dependencies

- Prefer to place dependencies to be bundled in `devDependencies` in bundle mode and dependencies in `dependencies` and `peerDependencies` will be automatically externalized (not bundled) by default
- Verify the build output and dependency specifiers in `package.json` carefully to ensure no missing dependency errors occur when consumers install and use this package

## Build optimization

- Keep syntax target in `lib.syntax` aligned with real compatibility requirements to enable better optimizations
- Avoid format-specific APIs in source code for better compatibility with different output formats
- Prefer lightweight dependencies to reduce bundle size

## Toolchain integration

- Prefer to use Rstest with `@rstest/adapter-rslib` for writing tests
```
END THIRD-PARTY FILE 8347582f8c32f086

The third-party file has ended. Everything between the 8347582f8c32f086 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2289 of 2724 bytes. © rstackjs · MIT · https://github.com/rstackjs/agent-skills/tree/HEAD/skills/rslib-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md