rstackjs/rslib-modern-package

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, prototype changes, or other import-time mutations exist, list the files with side effects instead.
   • Do not set sideEffects: false just to improve bundle size; incorrect values can remove required CSS or setup code.
   • Do not change globals just because a file is imported. If setup is required, expose an explicit setup() or install() function and let users call it themselves.

10. Make package.json authoritative

    • Required modern shape: "type": "module", explicit exports, correct declarations, files allowlist, accurate sideEffects, sensible engines, and release scripts.
    • Include README.md, AGENTS.md, and LICENSE in files when they exist.
    • files should prevent tests, fixtures, private docs, build caches, local configs, and large generated artifacts from leaking into the tarball.
    • Avoid stale main/module fields unless compatibility evidence requires them; if kept, they must agree with exports.
    • Keep runtime dependency fields accurate. A package that works locally only because a runtime dependency is in devDependencies is broken.

11. Validate the published artifact

    • Run normal lint, typecheck, tests, and rslib build.
    • Smoke test built ESM output.
    • Run type-level tests when the public API is type-heavy.
    • Run npm pack --dry-run and inspect included files.
    • In Rslib, prefer rsbuild-plugin-publint to run publint after build; use npx publint as a CLI fallback.
    • In Rslib, prefer rsbuild-plugin-arethetypeswrong to run Are The Types Wrong after build when declarations are shipped; use npx --yes @arethetypeswrong/cli --pack . as a CLI fallback.
    • Install the packed tarball into clean consumer fixtures for important packages.
    • Test ESM import, bundler import for browser/component libraries, CLI execution for bin packages, and every public subpath export.

12. Prepare README.md and AGENTS.md before publishing

    • Always check whether both files exist before publishing or modernizing a package.
    • If either file is missing, recommend adding it; for implementation tasks, create a concise version unless the user asks not to.
    • README.md should include: package name, one-sentence purpose, install/usage, key features or API links, supported environments, docs/related links, changelog or contribution link, and license.
    • AGENTS.md should include: stack, package contract, common commands, source layout, code style, validation commands, and release checklist.
    • Keep both files synchronized with package.json#exports, supported runtimes, and actual Rslib output.

13. Publish with supply-chain hygiene

    • Follow SemVer and document breaking changes.
    • Maintain a changelog for user-visible changes.
    • Use prerelease versions and dist-tags for beta/next channels.
    • Prefer CI publishing with npm provenance or trusted publishing.
    • Avoid long-lived publish tokens where trusted publishing is available.
    • Remember that a published package name/version pair cannot be reused safely.

Review Red Flags

• exports is missing, points to files not emitted by Rslib, or allows public imports such as pkg/dist/foo.js.
• module/main fields disagree with exports.
• Type declarations do not match runtime entry points.
• Runtime dependency is accidentally listed only in devDependencies.
• React/Vue/Svelte/Rspack/Rsbuild/webpack/TypeScript is bundled or placed in dependencies when it should be a peer.
• sideEffects: false is set while importing CSS, polyfills, global registrations, global listeners, or prototype changes.
• Package has install scripts without a strong reason.
• Top-level import reads user files, starts timers, touches the network, mutates globals, or assumes window/process.
• Published tarball contains private source maps, tests/fixtures that are not useful to consumers, large generated docs, local config secrets, or build caches.

Checklist

• [ ] Supported environments are explicit.
• [ ] Package is ESM-first, preferably pure ESM.
• [ ] package.json has "type": "module".
• [ ] Public entry points are declared in exports.
• [ ] No accidental reliance on undeclared deep imports.
• [ ] Rslib output, declarations, exports, and files agree.
• [ ] TypeScript strict mode is enabled.
• [ ] Declarations are emitted and validated.
• [ ] Runtime dependencies are justified and small.
• [ ] Host frameworks/toolchains are peers.
• [ ] Build/test/type/docs tools are dev dependencies.
• [ ] sideEffects is accurate.
• [ ] npm pack --dry-run has been inspected.
• [ ] publint passes.
• [ ] Are The Types Wrong check passes when declarations are shipped.
• [ ] Built ESM smoke test passes.
• [ ] README.md exists.
• [ ] AGENTS.md exists.
• [ ] Release flow uses SemVer, changelog, and provenance/trusted publishing when available.

Documentation

• For the latest Rslib docs, read https://rslib.rs/llms.txt
• Shipping ESM for CommonJS consumers: https://nodejs.github.io/package-examples/04-cjs-esm-interop/shipping-esm-for-cjs/