playbooks

home / skills / rstackjs / agent-skills / migrate-to-rslib

migrate-to-rslib skill

/skills/migrate-to-rslib

This skill guides migrating tsc or tsup projects to Rslib with minimal changes and clear verification.

npx playbooks add skill rstackjs/agent-skills --skill migrate-to-rslib

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.6 KB
---
name: migrate-to-rslib
description: Migrate tsc or tsup library projects to Rslib.
---

# Migrate to Rslib

## Goal

Migrate `tsc` and `tsup` projects to Rslib with minimal behavior changes and clear verification.

## Supported source frameworks

- tsc
- tsup

## Migration principles (must follow)

1. **Official guide first**: treat Rslib migration docs as source of truth.
2. **Smallest-change-first**: complete baseline migration first, then migrate advanced or custom behavior.
3. **Do not change business logic**: avoid touching source or business logic unless user explicitly asks.
4. **Validate before cleanup**: keep old tool dependencies/config temporarily if needed; remove only after Rslib is green.

## Workflow

1. **Detect source tool**
   - `tsup`
     - Config: `tsup.config.*`
     - Dependency: `tsup`
     - Build script: uses `tsup` to build projects
   - `tsc`
     - Config: `tsconfig.json` or `tsconfig.*.json`
     - Dependency: `typescript`
     - Build script: uses `tsc` to build projects. And it should be noted that `tsc` used only for type checking (e.g., `tsc --noEmit`) does not make it a `tsc` build project.

2. **Apply tool-specific migration deltas**
   - tsc: `references/tsc.md`
   - tsup: `references/tsup.md`

3. **Validate behavior**
   - Run build command to verify the project builds successfully.
   - If issues remain, compare the old project configuration with the migration guide and complete any missing mappings.

4. **Cleanup and summarize**
   - Remove obsolete dependencies/config only after validation passes.
   - Summarize changed files, mapped options, and any remaining manual follow-ups.

Overview

This skill migrates TypeScript library projects that use tsc or tsup to Rslib with minimal behavior changes and verifiable results. It detects the source tool, applies targeted migration deltas, and guides validation and cleanup. The goal is a smallest-change migration that preserves business logic and provides a clear summary of what changed.

How this skill works

The skill scans the repository to detect whether the project is built with tsup or tsc by checking config files, dependencies, and build scripts. It applies tool-specific migration steps mapped from the official Rslib migration guidance to update build configuration, outputs, and scripts. After applying changes it runs the existing build command to validate the migrated setup and lists any remaining manual follow-ups or obsolete artifacts that can be removed once validation succeeds.

When to use it

  • You maintain a TypeScript library currently built with tsc or tsup and want to standardize on Rslib.
  • You need a migration that minimizes risk to runtime and business logic behavior.
  • You want automated detection and mapping of build options from tsup or tsc to Rslib.
  • You prefer validating the new setup before removing old build tooling.

Best practices

  • Follow the official Rslib migration docs as the primary source of truth during changes.
  • Perform a baseline migration first, then address advanced customizations separately.
  • Do not modify application business logic during migration unless explicitly required.
  • Keep old build dependencies and configs temporarily until Rslib builds are verified.
  • Summarize changed files, mapped options, and manual follow-ups for reviewers.

Example use cases

  • Convert a monorepo package that uses tsup.config.js to an equivalent Rslib configuration while keeping output formats identical.
  • Migrate a library using tsc composite builds to Rslib references and verify the build graph without touching source code.
  • Replace tsup build scripts in package.json with Rslib scripts and validate by running the original build command.
  • Perform a staged migration where old dependencies remain until Rslib passes CI builds, then remove obsolete tools.

FAQ

Will this change my application code or business logic?

No. The migration focuses on build configuration and scripts. Source and business logic remain unchanged unless you explicitly request code modifications.

What if the migrated build fails?

Run the original build and compare configurations against the Rslib migration guide. The skill reports missing mappings and recommends targeted fixes before cleanup.

Can I remove old dependencies immediately after migration?

No. Keep old tooling until you verify Rslib builds cleanly. Remove obsolete dependencies and configs only after validation passes.