rslib-best-practices

$npx mdskill add rstackjs/agent-skills/rslib-best-practices

Optimize Rslib projects through configuration, CLI, and build rules.

  • Enforces standards for config, CLI, output, declarations, and dependencies.
  • Integrates with Rslib, Rsbuild, Rspack, and TypeScript toolchains.
  • Selects recommendations based on project type and specific requirements.
  • Delivers actionable guidance for writing, reviewing, and troubleshooting.

SKILL.md

.github/skills/rslib-best-practicesView on GitHub ↗
---
name: rslib-best-practices
description: Rslib best practices for config, CLI workflow, output, declaration files, dependency handling, build optimization and toolchain integration. Use when writing, reviewing, or troubleshooting Rslib projects.
---

# 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 build` to build
- Use `rslib build --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
- Prefer to use Rspress for writing library documentation, with `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` for component previews and API docs

## Debugging

- Run with `DEBUG=rsbuild` when diagnosing config resolution or plugin behavior
- Read generated files in `dist/.rsbuild` to confirm final Rsbuild/Rspack config, not assumed config

## Documentation

- For the latest Rslib docs, read https://rslib.rs/llms.txt

More from rstackjs/agent-skills

SkillDescription
migrate-to-rsbuildMigrate webpack, Vite, create-react-app (CRA/CRACO), or Vue CLI projects to Rsbuild.
migrate-to-rslibMigrate tsc or tsup library projects to Rslib.
migrate-to-rstestMigrate Jest or Vitest test suites and configs to Rstest. Use when asked to move from Jest/Vitest to Rstest, replace framework APIs with `@rstest/core`, translate test config to `rstest.config.ts`, or update test scripts and setup files for Rstest equivalents.
pr-creatorUse when asked to create a pull request for this repository. It helps the PR follow the repository's branch safety rules, title convention, pull request template, and concise English writing style.
rsbuild-best-practicesRsbuild best practices for config, CLI workflow, type checking, bundle optimization, assets, and debugging. Use when writing, reviewing, or troubleshooting Rsbuild projects.
rsbuild-v2-upgradeUse when upgrading a Rsbuild 1.x project to v2, including dependency and configuration updates.
rsdoctor-analysisUse when analyzing Rspack/Webpack bundles from local `rsdoctor-data.json` and producing evidence-based optimization recommendations.
rspack-best-practicesRspack best practices for config, CLI workflow, type checking, CSS, bundle optimization, assets and profiling. Use when writing, reviewing, or troubleshooting Rspack projects.
rspack-debuggingHelps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.
rspack-split-chunks>-