rslib-best-practices

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
• 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