rslib-modern-package

What this skill does

# Rslib Modern Package

Use this skill when creating a new Rslib library, modernizing an existing JS/TS package, or reviewing a package against an opinionated modern library standard.

This skill is opinionated: it describes a recommended modern package contract and may suggest breaking changes when they make the package simpler, safer, and easier for modern consumers.

## Standard

Default recommendation for new JS/TS libraries:

- ESM-first, preferably pure ESM.
- Strict TypeScript and correct declaration files.
- Explicit public API through `package.json#exports`.
- Small named-export API surface.
- Few runtime dependencies, without treating zero dependencies as a religion.
- Small, tree-shakeable output with accurate `sideEffects`.
- Clear dependency placement: runtime dependencies, peer dependencies, optional dependencies, and dev dependencies are not interchangeable.
- Published package is tested as an artifact, not just as source files.
- Release flow is automated, traceable, and SemVer-aware.
- README.md explains usage for humans; AGENTS.md preserves package invariants for future agents.

## Workflow

1. **Inspect the package contract first**
   - Read `package.json`, lockfile/package manager, `rslib.config.*`, `tsconfig*`, CI/release config, README.md, AGENTS.md, and existing `dist` output.
   - Identify package kind: Node utility, browser library, isomorphic utility, CLI, UI/component library, framework plugin, SDK, or adapter.
   - List supported runtimes, current entry points, deep imports, runtime dependencies, peer dependencies, optional integrations, files with side effects, and published files.
   - Run `npm pack --dry-run` early when changing package shape so the real tarball contents guide the review.

2. **Define target environments explicitly**
   - Do not say "supports modern environments" without defining them.
   - Verify the current Node.js release schedule before choosing `engines`.
   - As of May 9, 2026, Node.js 22 and 24 are LTS, and Node.js 20 is EOL. For new Node-facing packages, recommend `engines.node >=22` unless real consumers need an older runtime.
   - Browser packages should state whether they require native ESM, a bundler, Workers support, SSR compatibility, DOM APIs, CSS processing, or specific browser baselines.
   - Compatibility drops are breaking changes: old Node/browser versions, undocumented deep imports, default/named export shape, bundled vs external dependency behavior, and import side effects.

3. **Prefer pure ESM, but explain compatibility cost**
   - New packages should use `"type": "module"` and ESM source/output.
   - Rslib's default format is ESM; keep that default unless there is a clear reason to add another format.
   - Evaluate compatibility from real consumers and supported runtimes instead of assuming every historical module format is required.
   - Modern Node.js can load synchronous ESM from CommonJS via `require(esm)`; do not assume CJS consumers always require a separate CJS build.
   - If you rely on `require(esm)` compatibility, document and test its constraints: supported Node versions, no top-level `await` in the loaded graph, namespace-object return shape, default export behavior, and CJS/ESM cycle limits.
   - Prefer Node built-in specifiers such as `node:fs/promises`.

4. **Make `exports` the public API**
   - Treat `package.json#exports` as the product contract.
   - Export only paths users are meant to import.
   - Do not allow imports like `pkg/dist/foo.js` by exporting `./dist/*`. That makes the generated output layout part of the public API and turns internal file moves into breaking changes.
   - Instead, expose only intentional public paths such as `pkg` and `pkg/foo.js`, mapped to the actual files in `dist`.
   - Keep subpath style consistent: either all with extensions such as `./foo.js`, or all without extensions. Prefer paths with extensions when browser import maps matter.
   - Keep `"types"` first inside conditional exports.
   - Adding `exports` to an older package can be breaking because undeclared deep imports stop working.
   - Add `./package.json` only when consumers legitimately need package metadata.

5. **Design a small API surface**
   - Prefer named exports for multi-API packages.
   - Avoid default-export objects that gather every function into one object.
   - Public functions should be few, stable, well-named, and semver-maintained.
   - Keep internal types, caches, helper functions, adapter details, and error internals private unless they are part of the contract.
   - Avoid top-level work during import: file scans, network calls, timers, process mutation, global registration, DOM access, prototype mutation, or environment detection with side effects.
   - Async APIs that may be canceled should accept `AbortSignal`.
   - Prefer stable error classes, error codes, or typed error shapes over string matching.

6. **Use Rslib as the implementation path, not the whole standard**
   - For detailed Rslib configuration guidance, use the `rslib-best-practices` skill.
   - In this skill, only check whether Rslib output, declarations, `package.json#exports`, `files`, dependencies, and docs agree with the modern package contract.
   - Keep Rslib configuration small and intentional; avoid adding build complexity that does not improve the package contract.

7. **Keep dependencies small and intentional**
   - Start from platform APIs, not from dependency search.
   - Prefer built-ins when the runtime supports them: `URL`, `URLSearchParams`, `Intl`, `fetch`, `AbortController`, `structuredClone`, `crypto.randomUUID`, Web Streams, `TextEncoder`, `TextDecoder`, `node:fs/promises`, and `node:crypto`.
   - Small runtime dependencies are fine when they reduce maintenance risk or implementation complexity.
   - Avoid large utility packages for one or two helpers.
   - Evaluate dependencies for ESM support, `exports`, types, transitive dependency count, package size, license, maintenance activity, security history, install scripts, side effects, native install fragility, and granular imports.
   - Put required runtime packages in `dependencies`.
   - Put host-owned frameworks and toolchains in `peerDependencies`, such as React, Vue, Svelte, Rspack, Rsbuild, webpack, TypeScript, and framework runtimes.
   - Keep peer ranges reasonably broad; do not pin peers to a patch version unless required.
   - Put build tools, test tools, type tools, docs tools, and Rsbuild/Rspack plugins in `devDependencies`.
   - Use `optionalDependencies` or optional peers via `peerDependenciesMeta` for optional integrations.

8. **Make TypeScript strict and package-oriented**
   - Prefer TypeScript source for TS libraries; otherwise use high-quality JSDoc plus generated declarations.
   - With TypeScript 6 or tsgo-era defaults, strict checking may already be enabled; preserve that default and do not turn it off. For older TypeScript versions or inherited configs, set `strict: true` explicitly.
   - In Rslib projects, consider enabling `lib.dts.tsgo` to speed up declaration generation when the project can use tsgo.
   - Keep `module` and `moduleResolution` aligned with how declarations are emitted and how consumers resolve the package; NodeNext and bundler-style resolution are both valid in the right toolchain.
   - Use `verbatimModuleSyntax` so type-only imports/exports are explicit.
   - Use `isolatedDeclarations` when practical so exported APIs are explicit enough for declaration-oriented tooling.
   - Emit declarations; use declaration maps when editor navigation matters.
   - Use `import type` and `export type` for type-only dependencies.
   - Do not rely on consumers setting `skipLibCheck` to hide broken package types.
   - Test declarations as consumers see them, especially when using subpath exports.

9. **Keep `sideEffects` accurate**
   - Use `sideEffects: false` only when importing package files has no top-level side effects.
   - If CSS, polyfills, registrations, global listeners, prototy