Skip to main content
skill CX Codex

rslib-modern-package — Claude Code skill for npm packages

The rslib-modern-package skill guides agents through building or reviewing JS/TS libraries with Rslib, from package exports to release readiness. Use it for a new library or a package refresh.

MIT 125 installs ★ 100 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rstackjs/agent-skills --skill rslib-modern-package -a claude-code
Open on GitHub

What rslib-modern-package does

The skill lays out a package baseline: ESM-first output, strict TypeScript, a deliberate public surface in package.json#exports, and a lean set of runtime dependencies. It also recommends checking the published archive itself rather than treating source files as the whole product.

The workflow has the agent inspect package metadata, the lockfile, Rslib and TypeScript configuration, CI, docs, and existing dist output. When package layout changes, it calls for an early npm pack --dry-run to inspect the archive. Guidance is shaped by the library’s kind and target environments.

Its recommendations are opinionated. Adding exports can break consumers that rely on undeclared deep imports, and dropping a module format can also be a breaking change. The skill accepts such changes when they simplify the package contract, so assess their impact on existing consumers.

What it helps with

  • define intentional import paths with package.json#exports
  • inspect which files will ship in the npm archive
  • sort dependencies by purpose and ownership
  • spot compatibility risks during a package refresh
  • check Rslib output and TypeScript declarations against the package contract

Example prompts for the agent

  • Review this JS library against a modern package baseline and propose changes.
  • Inspect package.json and dist; which import paths should be public?
  • Check the package archive and assess whether adding exports could break current imports.

How to install rslib-modern-package

1Skills CLI (Vercel)

npx skills add rstackjs/agent-skills --skill rslib-modern-package -a claude-code

2Manually: put the files in place

~/.claude/skills/rslib-modern-package/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rslib-modern-package/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rslib-modern-package

How do I install rslib-modern-package in Claude Code?

Run npx skills add rstackjs/agent-skills --skill rslib-modern-package -a claude-code, then use ~/.claude/skills/rslib-modern-package/SKILL.md.

What does rslib-modern-package do?

It guides agents creating, updating, or reviewing JS/TS npm libraries, with recommendations covering ESM, exports, types, dependencies, and publication.

Can this skill recommend breaking changes?

Yes. For instance, adding exports can block deep imports that were never declared as public paths. Check the effect on existing consumers before adopting that change.

Source text

SKILL.md · MIT
---
name: rslib-modern-package
description: Design, modernize, or review JS/TS npm packages using an opinionated Rslib baseline for ESM, exports, types, dependencies, and release readiness.
---

# 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/

© rstackjs · MIT · rstackjs/agent-skills

Similar skills

SKILL.md skills catalog →
modern-web-guidance GoogleChrome The modern-web-guidance Claude Code skill finds current guidance for HTML, CSS, and client-side JavaScript. It runs before work on web interfaces, styles, or browser-side logic. CX Codex +1 62,500installs modern-javascript-patterns Seth Hobson The modern-javascript-patterns skill guides JavaScript refactors and async work with ES6+ syntax and functional patterns. It includes practical recommendations for code structure. CX Codex +1 21,553installs flutter-use-http-package flutter The flutter-use-http-package skill shows how to send GET, POST, PUT, and DELETE requests with Flutter's http package and handle JSON responses. Use it when an app needs to read from or write to a REST API. CX Codex +1 39,100installs modern-python trailofbits modern-python configures Python projects with a modern tooling stack: uv for dependency management, ruff for linting and formatting, ty for type checking. Use when starting new projects, writing scripts, or migrating from legacy tools. CX Codex +1 9,700installs dart-resolve-package-conflicts dart-lang dart-resolve-package-conflicts — a skill for resolving Dart package version conflicts when pub get fails. Teaches how to audit dependencies, update packages within constraints, and surgically remove entries from the lockfile. CX Codex +1 20,600installs dart-migrate-to-checks-package dart-lang dart-migrate-to-checks-package migrates Dart test suites from legacy package:matcher to package:checks. Useful when modernizing test assertions for static type safety and detailed diagnostics. CX Codex +1 20,000installs

From the same set21

The whole set →
migrate-to-rsbuild migrate-to-rsbuild — a skill that migrates webpack, Vite, Create React App, and Vue CLI projects to Rsbuild. It rewrites build configs and validates dev servers before cleaning up old packages. CX Codex +1 342installs rspack-tracing rspack-tracing — a skill for Claude Code and other IDEs that captures and analyzes Rspack build traces to pinpoint slow compiler phases, plugins, and loaders. Diagnose performance bottlenecks and crashes during development. CX Codex +1 291installs rspack-debugging rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust. CX Codex +1 282installs storybook-rsbuild The storybook-rsbuild skill sets up Storybook with Rsbuild or migrates an existing project from webpack or Vite. It also handles integrations with Rslib, Modern.js, and Rspack. CX Codex +1 212installs migrate-to-rslib migrate-to-rslib converts TypeScript library builds from tsc or tsup to Rslib with validation before cleanup. CX Codex +1 201installs rspack-split-chunks rspack-split-chunks teaches the agent to diagnose and tune optimization.splitChunks in Rspack: find duplicate modules, over-fetching, cache group issues, and oversized chunks. CX Codex +1 187installs rspress-v2-upgrade The rspress-v2-upgrade skill automates upgrading an Rspress project from v1 to v2. It reads the config, updates dependencies, rewrites import paths, and validates the build against the official migration guide. CX Codex +1 150installs rstest-debugging rstest-debugging diagnoses Rstest startup, build, runtime, logging, memory, and performance issues with traces and comparable measurements. CX Codex +1 133installs

Project sponsors

Companies that keep this analytics open