Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

rslib-modern-package

Opinionated Rslib recommendations for modern JS/TS npm package design covering pure ESM, strict TypeScript, explicit exports, small stable APIs, pragmatic dependencies, accurate sideEffects, correct declarations, package validation, provenance, README.md, and AGENTS.md. Use when the user wants to make a JS/TS package more modern, check whether the current package setup is healthy, review package.json/exports/types/dependencies/docs/release readiness, or apply a modern library baseline.

rstackjs · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add rstackjs/agent-skills --skill rslib-modern-package

About this skill


name: rslib-modern-package description: Opinionated Rslib recommendations for modern JS/TS npm package design covering pure ESM, strict TypeScript, explicit exports, small stable APIs, pragmatic dependencies, accurate sideEffects, correct declarations, package validation, provenance, README.md, and AGENTS.md. Use when the user wants to make a JS/TS package more modern, check whether the current package setup is healthy, review package.json/exports/types/dependencies/docs/release readiness, or apply a modern library baseline.

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 b
Read the complete source ↗