| name | rstack-repo-maintain |
| description | Audit and modernize RstackJS/Rspack ecosystem repositories to the current shared infrastructure baseline: Rslib ESM or dual builds, Rslint recommended rules, Rstest test tooling, Node 20+ support where appropriate, TypeScript 6 and tsgo where compatible, concise README/AGENTS docs, release workflow cleanup, unused dependency removal, and infra PR commit conventions. Use when updating rstackjs repositories, copying infra patterns from maintained exemplars, or reviewing package/tooling consistency. |
| metadata | {"internal":true} |
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
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.