Rstack Repo Maintain

Rstack Repo Maintain

Overview

Modernize RstackJS repositories without blindly copying config. Use current repository state and recently maintained exemplar repos to make small, verifiable infrastructure upgrades.

Baseline Evidence

Read references/repo-baselines.md when choosing a template repo, explaining where the baseline came from, or deciding whether a migration should be pure ESM, dual package, Node 20+, TypeScript 6, Rslint, Rstest, or tsgo.

Default starting points:

• Primary small-package baseline: rstackjs/rslog.
• Pure ESM and Node 20 plugin package baseline: rstackjs/rsbuild-plugin-publint.
• Concise AGENTS.md and tsgo/publint reference: rstackjs/rslog.
• Additional package validation reference: rstackjs/rsbuild-plugin-arethetypeswrong.
• Additional Rslib dts.tsgo implementation reference: rstackjs/rsbuild-plugin-virtual-module.

Always re-check the target repo and exemplar repo before editing. The reference file is a dated snapshot, not a permanent source of truth.

Workflow

1. Inventory the target repo

• Read package.json, lockfile, rslib.config.*, rslint.config.*, rstest.config.*, vitest.config.*, jest.config.*, playwright.config.*, tsconfig*.json, .github/workflows/*, README.md, AGENTS.md, release config, and source entry points.
• Identify package kind: library, Rsbuild/Rspack plugin, CLI, app template, test fixture, or docs package.
• List current build, lint, typecheck, test, release, and package manager commands before changing them.

1. Choose the migration target

• Prefer pure ESM for modern libraries and plugins when consumers can support it.
• Use dual package output only as a deliberate transition when existing CommonJS consumers or public exports require it.
• Treat runtime support, package exports, CLI bins, side effects, and documented deep imports as compatibility constraints.

1. Update the infrastructure in small layers

• Rslib: use rslib for builds, keep config minimal, set appropriate lib.syntax, emit declarations, and align package.json#exports with real output. Add rsbuild-plugin-publint when the package should validate publish metadata during build.
• Rslint: use @rslint/core; use ts.configs.recommended for TypeScript packages. Add js.configs.recommended only when JavaScript source or config files are intentionally linted.
• Prettier: if the repo already carries Prettier or should check formatting, wire it into lint scripts with the repo's established style (prettier --check . / prettier --write . or -c / -w) and keep generated artifacts ignored by .prettierignore.
• Test tooling: prefer Rstest for JavaScript/TypeScript unit tests in Rstack repositories. When a repo still uses Vitest or Jest, use the migrate-to-rstest skill, map scripts and configs to @rstest/core, keep Playwright or other browser E2E tooling separate, and remove legacy runner deps/configs only after the migrated scope is green.
• Node/CI: verify the effective Node support policy from code, dependencies, CI, and release workflows. Do not blindly add a Node 20 matrix or an extra CI build step when the maintained baseline intentionally keeps CI latest-only for speed or already builds in release.
• GitHub Actions: keep .github/workflows/* aligned with the chosen baseline repo. Pin third-party actions to commit hashes, not floating tags, and update action pins by copying or refreshing the baseline pattern instead of inventing new pins.
• TypeScript: upgrade to TypeScript 6, remove stale/deprecated compiler options, prefer target: "ES2023" for Node 20+ packages, and keep module resolution consistent with runtime output.
• tsgo: enable Rslib declaration dts: { tsgo: true } only after checking compatibility with declaration bundling, package shape, and installed @typescript/native-preview. Pin native-preview to an exact version and validate emitted declarations plus package contents.
• Docs: keep README.md focused on purpose, install, usage, options, supported runtimes, release/license links. Add a concise AGENTS.md in the rsbuild-style shape: Stack, Commands, Project structure, and Code style.
• Dependency cleanup: run a repo-appropriate unused dependency check such as Knip when feasible, then remove only dependencies proven unused or misplaced. Do not add Knip as a dependency unless the repo starts using it in scripts; treat pnpm stage and tsgo tool dependencies as known false positives when applicable.

1. Preserve behavior while modernizing

• Do not touch business logic unless the infra change requires it.
• Keep compatibility breaks explicit in commit/PR notes: ESM-only output, removed exports, changed CLI behavior, or dependency placement changes.
• If a repo needs multiple risky changes, split them into reviewable PR-sized batches.

1. Prepare the infra PR

• Create the infrastructure update branch from the latest origin/main unless the user asks for a different base.
• Use a specific PR title starting with chore(infra):, for example chore(infra): enable tsgo and package validation or chore(infra): align build and lint tooling.
• Keep each tool update or tool configuration as its own commit unit. Use commit titles such as chore(deps): update rslint to 0.6.1, chore(infra/tsgo): enable tsgo declaration build, or chore(infra/ci): pin workflow actions.
• Do not mix unrelated tool changes, generated lockfile updates, and source fixes in a single commit unless the tool update requires them to stay atomic.

1. Validate before cleanup

• Run install with the repo package manager.
• Run lint, typecheck if present, build, and tests.
• Run npm pack --dry-run or the repo's publish dry-run path for packages.
• Smoke test import/CLI paths that changed.
• Remove obsolete configs and dependencies only after the new path is green.

Output

When reporting back, include:

• Target baseline and why it was chosen.
• Files changed, grouped by build/lint/TypeScript/CI/docs/dependencies.
• Breaking changes or compatibility risks.
• Commands run and their result.
• Any deliberate deviations from the Rstack baseline.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rstackjs
• Source: rstackjs/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.