@bleedingdev/modern-js-create 3.2.0-ultramodern.6 → 3.2.0-ultramodern.7

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor-rspack.md

@@ -0,0 +1,138 @@
+# Install Rsdoctor Plugin for Rspack Projects
+
+This guide covers installation for Rspack-based projects, including:
+
+- Rspack CLI
+- Rsbuild
+- Modern.js
+- Rslib
+- Rspress
+
+## Step 1: Install Dependencies
+
+For projects based on Rspack, such as Rsbuild or Rslib:
+
+**Note:** Prefer using the latest versions of the above dependencies when available.
+
+```bash
+npm add @rsdoctor/rspack-plugin -D
+pnpm add @rsdoctor/rspack-plugin -D
+```
+
+## Step 2: Register Plugin
+
+After the dependency installation, check the installed `@rsdoctor/rspack-plugin` version before changing config or running a build. Do not infer plugin capabilities from `@rsdoctor/agent-cli --version`.
+
+Required version gate (use exactly this if/else order):
+
+1. Set `pluginName = '@rsdoctor/rspack-plugin'`.
+2. Determine `pluginVersion` from local files first: dependency declarations in `package.json`, lockfile entries, then `node_modules/@rsdoctor/rspack-plugin/package.json` if installed. Use `pnpm why @rsdoctor/rspack-plugin` / `npm ls @rsdoctor/rspack-plugin` only as a fallback. When repeating analysis, reuse a valid `.rsdoctor-analysis-cache.json` plugin entry before re-reading files; invalidate it if `package.json`, lock files, or the plugin package file modification time changed.
+3. Choose one branch; do not merge branches:
+
+```text
+if @rsdoctor/rspack-plugin is missing:
+  install/register @rsdoctor/rspack-plugin, then configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion is unknown:
+  resolve pluginVersion first; if still unknown, configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion >= 1.5.11:
+  do not modify plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
+else: # pluginVersion < 1.5.11
+  MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+```
+
+Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11`, `RSDOCTOR_OUTPUT=json` is forbidden. For example, when `@rsdoctor/rspack-plugin` is `1.5.7`, this command is incorrect:
+
+```bash
+RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build:rspack
+```
+
+Below are configuration examples for old Rspack plugin versions, unknown versions, missing plugins, or projects that still need to register the plugin:
+
+### Rspack CLI
+
+Initialize the plugin in the [plugins](https://www.rspack.rs/config/plugins.html#plugins) of `rspack.config.ts`:
+
+```ts title="rspack.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugins: [
+    // Only register the plugin when RSDOCTOR is true, as the plugin will increase the build time.
+    process.env.RSDOCTOR &&
+      new RsdoctorRspackPlugin({
+        disableClientServer: true,
+        // Required for @rsdoctor/rspack-plugin < 1.5.11.
+        output: {
+          mode: 'brief',
+          options: {
+            type: ['json'],
+          },
+        },
+      }),
+  ],
+};
+```
+
+### Rsbuild/Rslib/Modern.js
+
+See [Rsbuild - Use Rsdoctor](https://rsbuild.rs/guide/debug/rsdoctor) for more details.
+If this is Modern.js project can see [tools.rspack](https://modernjs.dev/configure/app/tools/rspack) of `modern.config.ts`:
+
+For `@rsdoctor/rspack-plugin` < `1.5.11`, configure JSON output in `rsbuild.config.ts`:
+
+```ts title="rsbuild.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  tools: {
+    rspack: {
+      plugins: [
+        process.env.RSDOCTOR === 'true' &&
+          new RsdoctorRspackPlugin({
+            disableClientServer: true, // Prevent starting local server
+            output: {
+              mode: 'brief', // Required for plugin versions < 1.5.11
+              options: {
+                type: ['json'], // Only generate JSON data
+              },
+            },
+          }),
+      ],
+    },
+  },
+};
+```
+
+### Rspress
+
+For Rspress projects, configure the plugin in `builderConfig.tools.rspack`:
+
+```ts title="rspress.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  builderConfig: {
+    tools: {
+      rspack: {
+        plugins: [
+          process.env.RSDOCTOR === 'true' &&
+            new RsdoctorRspackPlugin({
+              disableClientServer: true, // Prevent starting local server
+              output: {
+                mode: 'brief', // Required for plugin versions < 1.5.11
+                options: {
+                  type: ['json'], // Only generate JSON data
+                },
+              },
+            }),
+        ],
+      },
+    },
+  },
+});
+```
+
+## Step 3 & 4: Locate and Use rsdoctor-data.json
+
+For steps on locating the `rsdoctor-data.json` file and using it for analysis, see the [common installation guide](./install-rsdoctor-common.md).

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor-webpack.md

@@ -0,0 +1,71 @@
+# Install Rsdoctor Plugin for Webpack Projects
+
+This guide covers installation for Webpack projects (webpack >= 5).
+
+## Step 1: Install Dependencies
+
+Rsdoctor only supports webpack >= 5.
+
+For projects based on webpack:
+
+```bash
+npm add @rsdoctor/webpack-plugin -D
+pnpm add @rsdoctor/webpack-plugin -D
+```
+
+## Step 2: Register Plugin
+
+After the dependency installation, check the installed `@rsdoctor/webpack-plugin` version before changing config or running a build. Do not infer plugin capabilities from `@rsdoctor/agent-cli --version`.
+
+Required version gate (use exactly this if/else order):
+
+1. Set `pluginName = '@rsdoctor/webpack-plugin'`.
+2. Determine `pluginVersion` from local files first: dependency declarations in `package.json`, lockfile entries, then `node_modules/@rsdoctor/webpack-plugin/package.json` if installed. Use `pnpm why @rsdoctor/webpack-plugin` / `npm ls @rsdoctor/webpack-plugin` only as a fallback. When repeating analysis, reuse a valid `.rsdoctor-analysis-cache.json` plugin entry before re-reading files; invalidate it if `package.json`, lock files, or the plugin package file modification time changed.
+3. Choose one branch; do not merge branches:
+
+```text
+if @rsdoctor/webpack-plugin is missing:
+  install/register @rsdoctor/webpack-plugin, then configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion is unknown:
+  resolve pluginVersion first; if still unknown, configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+else if pluginVersion >= 1.5.11:
+  do not modify plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
+else: # pluginVersion < 1.5.11
+  MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only
+```
+
+Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11`, `RSDOCTOR_OUTPUT=json` is forbidden. For example, when `@rsdoctor/webpack-plugin` is `1.5.7`, this command is incorrect:
+
+```bash
+RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build
+```
+
+### Webpack
+
+For old Webpack plugin versions, unknown versions, missing plugins, or projects that still need to register the plugin, initialize it in the [plugins](https://webpack.js.org/configuration/plugins/#plugins) of `webpack.config.js`:
+
+```js title="webpack.config.js"
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+
+module.exports = {
+  // ...
+  plugins: [
+    // Only register the plugin when RSDOCTOR is true, as the plugin will increase the build time.
+    process.env.RSDOCTOR &&
+      new RsdoctorWebpackPlugin({
+        disableClientServer: true,
+        // Required for @rsdoctor/webpack-plugin < 1.5.11.
+        output: {
+          mode: 'brief',
+          options: {
+            type: ['json'],
+          },
+        },
+      }),
+  ].filter(Boolean),
+};
+```
+
+## Step 3 & 4: Locate and Use rsdoctor-data.json
+
+For steps on locating the `rsdoctor-data.json` file and using it for analysis, see the [common installation guide](./install-rsdoctor-common.md).

package/template-workspace/.agents/skills/rsdoctor-analysis/references/install-rsdoctor.md

@@ -0,0 +1,39 @@
+# Install Rsdoctor Plugin
+
+This documentation has been split into project-specific guides:
+
+## Choose Your Project Type
+
+- **For Rspack/Rsbuild/Modern.js projects:** See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+- **For Webpack projects:** See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+## Quick Decision Guide
+
+**Determine your project type:**
+
+1. **Check project type** (`projectType`):
+   - If project uses **Rspack** (including Rsbuild, Rslib, or any Rspack-based project) → Use `projectType: 'rspack'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If project uses **Webpack** (webpack >= 5) → Use `projectType: 'webpack'` → See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+2. **Check framework** (`framework`):
+   - If using **Rspack CLI** → `framework: 'rspack'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rsbuild** → `framework: 'rsbuild'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Modern.js** → `framework: 'modern.js'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rslib** → `framework: 'rslib'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Rspress** → `framework: 'rspress'` → See [install-rsdoctor-rspack.md](./install-rsdoctor-rspack.md)
+   - If using **Webpack** → `framework: 'webpack'` → See [install-rsdoctor-webpack.md](./install-rsdoctor-webpack.md)
+
+**Decision flow:**
+
+```
+User's project
+├─ Is it Rspack-based? (Rsbuild, Rslib, Rspress, etc.)
+│  ├─ Yes → projectType: 'rspack'
+│  │  ├─ Rspack CLI? → framework: 'rspack' → install-rsdoctor-rspack.md
+│  │  ├─ Rsbuild? → framework: 'rsbuild' → install-rsdoctor-rspack.md
+│  │  ├─ Rslib? → framework: 'rslib' → install-rsdoctor-rspack.md
+│  │  ├─ Rspress? → framework: 'rspress' → install-rsdoctor-rspack.md
+│  │  └─ Modern.js? → framework: 'modern.js' → install-rsdoctor-rspack.md
+│  └─ No → Is it Webpack >= 5?
+│     └─ Yes → projectType: 'webpack', framework: 'webpack' → install-rsdoctor-webpack.md
+```

package/template-workspace/.agents/skills/rsdoctor-analysis/references/rsdoctor-data-types.md

@@ -0,0 +1,103 @@
+# Rsdoctor Data Type Context
+
+Use this reference when a task requires understanding raw `rsdoctor-data.json` fields, schema, or nested data attributes.
+
+## Source of Truth
+
+Read type definitions from the published npm package `@rsdoctor/types`. Do not use local repository `dist/` artifacts unless the user explicitly asks for local development branch behavior.
+
+Brief JSON output has this wrapper shape:
+
+```ts
+import type { Manifest, SDK } from '@rsdoctor/types';
+
+export interface RsdoctorDataJson {
+  data: SDK.BuilderStoreData;
+  clientRoutes: Manifest.RsdoctorManifestClientRoutes[];
+}
+```
+
+The core payload type is `SDK.BuilderStoreData`.
+
+## npm Lookup Flow
+
+Prefer the npm registry/package interface.
+
+Use the latest published package unless the user gives a specific Rsdoctor package version or asks to match an installed project version.
+
+```bash
+npm view @rsdoctor/types version dist.tarball --json
+```
+
+If command execution is unavailable, use the registry endpoint directly:
+
+```text
+https://registry.npmjs.org/@rsdoctor%2Ftypes/latest
+```
+
+Read the `dist.tarball` URL from the response, download the tarball, and inspect `.d.ts` files under `package/dist/`.
+
+If matching an installed project version is important:
+
+1. Inspect the project package versions for `@rsdoctor/rspack-plugin`, `@rsdoctor/webpack-plugin`, `@rsdoctor/core`, `@rsdoctor/sdk`, or `@rsdoctor/types`.
+2. Query the matching type package:
+
+```bash
+npm view @rsdoctor/types@<version> version dist.tarball --json
+```
+
+3. If that exact version does not exist, use the closest compatible published `@rsdoctor/types` version and state the version mismatch.
+
+## Files to Inspect
+
+Start here:
+
+- `package/dist/index.d.ts`: namespace exports. `SDK` comes from `./sdk/index.js`; `Manifest` comes from `./manifest.js`.
+- `package/dist/sdk/index.d.ts`: exports all SDK data subtypes.
+- `package/dist/sdk/result.d.ts`: defines `BuilderStoreData`, the `rsdoctor-data.json.data` payload.
+- `package/dist/manifest.d.ts`: defines client routes and manifest types.
+
+Then load nested files as needed:
+
+- `package/dist/sdk/module.d.ts`: `moduleGraph`, modules, dependencies, source ranges, module code, tree-shaking-linked module data.
+- `package/dist/sdk/chunk.d.ts`: `chunkGraph`, assets, chunks, entrypoints.
+- `package/dist/sdk/package.d.ts`: `packageGraph`, package dependency data, duplicate package reports, other reports.
+- `package/dist/sdk/loader.d.ts`: loader timing/input/output data.
+- `package/dist/sdk/resolver.d.ts`: resolver data.
+- `package/dist/sdk/plugin.d.ts`: plugin hook/tap timing data.
+- `package/dist/sdk/summary.d.ts`: build summary/cost data.
+- `package/dist/sdk/config.d.ts`: collected bundler config data.
+- `package/dist/sdk/envinfo.d.ts`: environment info data.
+- `package/dist/rule/data.d.ts`: `errors`/rule store data.
+
+## Field Map
+
+`SDK.BuilderStoreData` contains:
+
+- `hash`: build hash.
+- `root`: project root.
+- `pid`: process id.
+- `envinfo`: environment information.
+- `errors`: rule/error store data.
+- `configs`: collected bundler config data.
+- `summary`: build summary data.
+- `resolver`: resolver events.
+- `loader`: loader transform events.
+- `plugin`: plugin hook/tap events.
+- `moduleGraph`: module graph data.
+- `chunkGraph`: asset/chunk/entrypoint graph data.
+- `packageGraph`: package/dependency graph data.
+- `moduleCodeMap`: module source/code map data.
+- `treeShaking`: optional tree-shaking data.
+- `otherReports`: optional extra report payloads.
+
+In brief JSON mode, `moduleCodeMap` is normally `{}` and `treeShaking` is normally absent unless generated by a mode that includes it.
+
+## Usage Guidance
+
+- Cite the npm package version used when explaining fields.
+- Distinguish wrapper fields (`data`, `clientRoutes`) from `SDK.BuilderStoreData` fields.
+- When a nested field is unclear, inspect the specific `.d.ts` file instead of guessing.
+- Use these types to construct `@rsdoctor/agent-cli --filter` field selections before each data fetch. Prefer the smallest field set that can answer the current question.
+- Match filters to the relevant data domain: chunks from `chunkGraph`, modules and tree-shaking module details from `moduleGraph`/`treeShaking`, packages from `packageGraph`, loader cost from `loader`, build cost from `summary`, and rule findings from `errors`.
+- For analysis recommendations, prefer `@rsdoctor/agent-cli` commands. Use these types for schema explanation, prompt grounding, or validating raw JSON field names.

package/template-workspace/.agents/skills/rslib-best-practices/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: rslib-best-practices
+description: Rslib best practices for config, CLI workflow, output, declaration files, dependency handling, build optimization and toolchain integration. Use when writing, reviewing, or troubleshooting Rslib projects.
+---
+
+# Rslib Best Practices
+
+Apply these rules when writing or reviewing Rslib library projects.
+
+## Configuration
+
+- Use `rslib.config.ts` and `defineConfig`
+- Check Rslib-specific configurations first (e.g., `lib.*`), and also leverage Rsbuild configurations (e.g., `source.*`, `output.*`, `tools.*`) as needed
+- For deep-level or advanced configuration needs, use `tools.rspack` or `tools.bundlerChain` to access Rspack's native configurations
+- In TypeScript projects, prefer `tsconfig.json` path aliases
+
+## CLI
+
+- Use `rslib` to build
+- Use `rslib --watch` to build in watch mode for local development
+- Use `rslib inspect` to inspect final Rslib/Rsbuild/Rspack configs
+
+## Output
+
+- Prefer to build pure-ESM package with `"type": "module"` in `package.json`
+- Prefer to use bundleless mode with `output.target` set to `'web'` when building component libraries
+- Prefer to use bundle mode when building Node.js utility libraries
+- Ensure `exports` field in `package.json` is correctly configured and matches the actual JavaScript output and declaration files output of different formats (ESM, CJS, etc.)
+
+## Declaration files
+
+- Prefer to enable declaration file generation with `lib.dts: true` or detailed configurations
+- For faster type generation, enable `lib.dts.tsgo` experimental feature with `@typescript/native-preview` installed
+
+## Dependencies
+
+- Prefer to place dependencies to be bundled in `devDependencies` in bundle mode and dependencies in `dependencies` and `peerDependencies` will be automatically externalized (not bundled) by default
+- Verify the build output and dependency specifiers in `package.json` carefully to ensure no missing dependency errors occur when consumers install and use this package
+
+## Build optimization
+
+- Keep syntax target in `lib.syntax` aligned with real compatibility requirements to enable better optimizations
+- Avoid format-specific APIs in source code for better compatibility with different output formats
+- Prefer lightweight dependencies to reduce bundle size
+
+## Toolchain integration
+
+- Prefer to use Rstest with `@rstest/adapter-rslib` for writing tests
+- Prefer to use Rspress for writing library documentation, with `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` for component previews and API docs
+
+## Debugging
+
+- Run with `DEBUG=rsbuild` when diagnosing config resolution or plugin behavior
+- Read generated files in `dist/.rsbuild` to confirm final Rsbuild/Rspack config, not assumed config
+
+## Documentation
+
+- For the latest Rslib docs, read https://rslib.rs/llms.txt

package/template-workspace/.agents/skills/rslib-modern-package/SKILL.md

@@ -0,0 +1,173 @@
+---
+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 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/

package/template-workspace/.agents/skills/rspack-best-practices/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: rspack-best-practices
+description: Rspack best practices for config, CLI workflow, type checking, CSS, bundle optimization, assets and profiling. Use when writing, reviewing, or troubleshooting Rspack projects.
+---
+
+# Rspack Best Practices
+
+Apply these rules when writing or reviewing Rspack projects.
+
+## Configuration
+
+- Use `rspack.config.ts` and `defineConfig`
+- Define explicit `entry` values for multi-page applications
+- Keep one main config and branch by `process.env.NODE_ENV` only when needed
+- Keep rule conditions narrow and explicit (`test`, `include`, `exclude`, `resourceQuery`)
+- Prefer built-in Rspack plugins/loaders over community JS alternatives when equivalent features exist
+
+## CLI
+
+If `@rspack/cli` is installed:
+
+- Use `rspack dev` for local development
+- Use `rspack build` for production build
+- Use `rspack preview` only for local production preview
+
+## Type checking
+
+- Use `ts-checker-rspack-plugin` for integrated dev/build type checks
+- Or run `tsc --noEmit`/`vue-tsc --noEmit` as an explicit script step
+
+## CSS
+
+Choose one strategy:
+
+- Built-in CSS (`type: 'css' | 'css/auto' | 'css/module'`) for modern setups
+- `css-loader` + `CssExtractRspackPlugin` for webpack migration compatibility
+- `style-loader` for pure style-in-JS runtime injection scenarios
+
+Optional:
+
+- Use `builtin:lightningcss-loader` when goals are syntax downgrade + vendor prefixing
+- Use `sass-loader`/`less-loader` for preprocessing Sass/Less files
+- Use `@tailwindcss/webpack` for Tailwind CSS integration
+
+## Bundle size optimization
+
+- Prefer dynamic `import()` for non-critical code paths
+- Prefer lightweight libraries where possible
+- Keep `target` aligned with real compatibility requirements
+
+## Asset management
+
+- Import source-managed assets from project source directories, not from `public`
+- Reference `public` files by absolute URL path
+- Prefer asset modules (`asset`, `asset/resource`, `asset/inline`, `asset/source`) over legacy `file-loader`/`url-loader`/`raw-loader`
+
+## Profiling
+
+- Use Node CPU profiling (`--cpu-prof`) when JavaScript-side overhead is suspected
+- Use `RSPACK_PROFILE=OVERVIEW` and analyze trace output for compiler-phase bottlenecks
+- Replace known slow stacks first (`babel-loader`, PostCSS, terser) with Rspack built-ins when feasible
+
+## Security
+
+- Do not publish `.map` files to public servers/CDNs when production source maps are enabled
+
+## Documentation
+
+- For the latest (v2) docs, read http://rspack.rs/llms.txt
+- For Rspack v1 docs, read http://v1.rspack.rs/llms.txt