Rsdoctor Analysis

Rsdoctor Analysis Assistant Skill

Use the globally installed rsdoctor-agent CLI from @rsdoctor/agent-cli only after a real rsdoctor-data.json path exists. Keep analysis read-only unless the user explicitly asks for install/config setup.

Response order (required): High-Priority Issues -> Proposed Solutions -> Optional Reference-Chain Follow-up Choices -> Next Deep-Dive Issue Categories (Not commands).

Core Workflow

1. Reuse current-session results and valid .rsdoctor-analysis-cache.json entries before doing new work. 2. Locate rsdoctor-data.json fast: user-provided path, then dist/rsdoctor-data.json, output/rsdoctor-data.json, static/rsdoctor-data.json, .rsdoctor/rsdoctor-data.json, then one bounded rg --files search excluding node_modules and .git. Treat manifest.json only as an index. 3. If data exists, skip all plugin version/config/build generation logic. Update cache when useful. 4. If data is missing, stop analysis: do not run rsdoctor-agent analysis commands, do not run the Analysis Gate, and either ask for the data path or run the Generation Gate below only when setup/generation is required. 5. After a real data file exists, run Analysis Gate at most once before the first rsdoctor-agent data-fetch command: verify global @rsdoctor/agent-cli with npm view @rsdoctor/agent-cli version and rsdoctor-agent --version; install latest only if missing/outdated, a version-related error occurs, or the user asks to refresh. 6. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible; synthesize findings in the required response order.

Performance rules: parallelize independent checks, cache only derived facts (dataFile, dataFileMtime, pluginName, pluginVersion, dependency/config/plugin modification times), and invalidate cache when paths disappear, modification times change, the user asks to refresh, or cached values fail. Speculative plugin checks must not trigger generation; use them only after confirming the data file is missing.

Generation Gate

Identify pluginName (@rsdoctor/rspack-plugin or @rsdoctor/webpack-plugin) and determine pluginVersion from local files first: package.json, lockfile, then node_modules/<plugin>/package.json; use pnpm why / npm ls only as fallback.

Use this exact if/else decision tree; do not merge branches:

if pluginName is missing:
  install/register the matching Rsdoctor 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 edit 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, it is forbidden. For < 1.5.11, generating rsdoctor-data.json requires the plugin config below:

output: {
  mode: 'brief',
  options: {
    type: ['json'],
  },
}

Evidence and Command Bounds

Default Evidence Set:

Scope rules:

• Use rsdoctor-agent for bundle data access only after rsdoctor-data.json exists; prefer parallel independent fetches; bound output with --filter, pagination, and --limit.
• Default analysis stays within the Default Evidence Set. For non-default analysis, choose minimal fields from references/rsdoctor-data-types.md and patterns from references/common-analysis-patterns.md.
• Treat chain tracing, broad commands, optimization edits, splitChunks experiments, and build re-runs as opt-in follow-ups that require user confirmation.
• For duplicate packages and tree-shaking issues, identify issues first; trace reference/import chains only after user confirmation.
• Prefer tree-shaking retained-modules --emitted-only --category side-effects --limit 10 with narrow --filter for side-effects investigations.
• For retained emitted modules, use tree-shaking retained-modules with --emitted-only, bounded --category, --sort gzipSize, --limit, and narrow --filter; do not pass --compact.
• Use tree-shaking summary only as fallback for missing fields or aggregate context. Treat tree-shaking bailout-reasons as high-volume; run it only when explicitly requested and pass target --modules (max 100).
• If any command exceeds 5k tokens, 500 KB raw output, or a few hundred transcript lines, stop broad fetching and switch to targeted compact queries.

Output and Recovery

Output format:

1. Issues found in the current build and recommended fixes:

• Group each issue with its fix recommendation.
• Include concrete evidence (size/time/count/path/rule code) and priority.
• For duplicate packages and tree-shaking issues, include a short "continue tracing vs stop here" choice.

2. Whether deeper analysis is still needed:

• List remaining issue categories only, not commands.

For Top-N insights, prefer a table: Name | Volume/Time | Count | Recommendation.

Recovery rules:

• rsdoctor-data.json missing: do not run rsdoctor-agent; ask for the data path or run Generation Gate, then use the matching install reference if setup is needed.
• Command not found: run Analysis Gate, then retry with rsdoctor-agent.
• query reports unknown tool: run list and use a catalog tool name, or switch to direct <group> <subcommand> mode.
• JSON read error: verify file path, JSON validity, and permissions.
• In Codex, do not run install, build, global CLI installation, version checks, or rsdoctor-agent... inside sandbox. Run Rsdoctor CLI setup and data-fetch commands outside sandbox so they can access project files and dependencies normally.

References: commands/options references/command-map.md; install/config/data location references/install-rsdoctor.md, references/install-rsdoctor-rspack.md, references/install-rsdoctor-webpack.md, references/install-rsdoctor-common.md; raw data fields references/rsdoctor-data-types.md; common patterns references/common-analysis-patterns.md.

Rsdoctor Skill Command Map

Stable CLI entry:

• Install and verify the global CLI first:
• npm view @rsdoctor/agent-cli version
• rsdoctor-agent --version
• If missing or outdated: npm install -g @rsdoctor/agent-cli@latest
• Run data-fetch commands directly with rsdoctor-agent <group> <subcommand> [options].

Top-level command mode:

• list
• query <tool-name> --data-file <path> [--input <json>]

query catalog (current):

• chunks_list
• packages_direct_dependencies
• packages_duplicates
• packages_similar
• build_summary
• bundle_optimize
• errors_list
• tree_shaking_summary

Option scopes:

• --data-file <path>:
• required for query, direct <group> <subcommand>, and ai <group> <subcommand>
• not required for list, ai --describe, ai --schema
• --input <json>: optional for query
• --filter <...>: supported by every data-fetch function; use it to return only required fields selected from @rsdoctor/types / rsdoctor-data-types.md
• --compact: add whenever possible to keep CLI JSON compact. Do not use it with tree-shaking retained-modules; use --filter and --limit instead.

Chunks

• chunks list -> List all chunks. Pagination: --page-number, --page-size
• chunks by-id --id <n> -> Get chunk detail by numeric id
• chunks large -> Find oversized chunks. High-noise in default analysis; avoid unless the user asks for chunk deep dive.

Modules

• modules by-id --id <id> -> Module detail by id
• modules by-path --path "<path>" -> Module lookup by path
• modules issuer --id <id> -> Issuer/import chain (recommended as second-pass, after user confirms chain tracing)
• modules exports -> Module exports info
• modules side-effects -> Non-tree-shakeable modules. Fallback only for side-effects analysis; use --page-size 10, narrow filters, and stop if output exceeds 5k tokens or 500 KB.

Packages

• packages list -> Package list with size/duplication info. Do not read full pages in default analysis; use fixed Top-N package summaries or narrowly filtered/package-targeted queries.
• packages by-name --name <pkg> -> Package lookup by name
• packages dependencies -> Dependency graph. Pagination: --page-number, --page-size
• packages direct-dependencies -> Direct third-party package dependencies imported by project/local packages. Tool name: packages_direct_dependencies
• packages duplicates -> Duplicate package detection (first-pass summary before optional chain tracing)
• packages similar -> Similar package detection

Assets

• assets list -> Asset list with size info
• assets diff --baseline <path> --current <path> -> Compare two builds
• assets media -> Media optimization guidance

Loaders

• loaders hot-files -> Slowest loader/file pairs. Options: --page-number, --page-size, --min-costs
• loaders directories -> Loader times by directory. Options: --page-number, --page-size, --min-total-costs

Build

• build summary -> Build summary and costs
• build entrypoints -> Entrypoints
• build config -> Build config snapshot
• build optimize -> Bundle optimization inputs. High-noise in default analysis; avoid unless the user asks for bundle optimization deep dive or default evidence is insufficient. Options: --step, --side-effects-page-number, --side-effects-page-size (recommend --side-effects-page-size 10).

Bundle

• bundle optimize -> Alias of build optimize

Errors

• errors list -> All errors and warnings
• errors by-code --code <code> -> Filter by code. For default E1001/E1002 summaries, prefer local JSON summarization.
• errors by-level --level <level> -> Filter by level

Rules

• rules list -> Rule scan results

Server

• server port -> Current JSON data file path

Tree-Shaking

• tree-shaking summary -> Overall tree-shaking health summary (can be very large; filter with fields from rsdoctor-data-types, compact where useful, and use aggregated results)
• tree-shaking retained-modules -> Retained emitted modules by category for tree-shaking diagnosis. Useful options: --emitted-only, --category cjs,barrel,side-effects, --sort gzipSize, --limit <n>, and --filter id,path,packageName,version,category,size,chunks,bailoutReason,recommendation. Does not support --compact.
• tree-shaking bailout-reasons --modules <module-list> -> Non-tree-shakeable modules by bailout reason for the provided modules. High-volume; only run when explicitly requested, always pass --modules, and include at most 100 modules per command.
• tree-shaking exports-analysis -> Export-level tree-shaking opportunities

tree-shaking retained-modules returns retained module rows with:

Common Analysis Patterns

Use this reference for common Rspack/Webpack bundle analysis questions after locating rsdoctor-data.json.

Similar Packages

Use direct dependency package data to inspect similar packages. Start with packages direct-dependencies or query packages_direct_dependencies, then check known package families and other potentially similar packages.

Suggested flow:

1. Fetch direct dependency package data with packages direct-dependencies or query packages_direct_dependencies. Use --filter fields for package name, version, issuer/dependency relation, and size when available. 2. Treat this direct dependency list as the replacement-candidate set. Do not make replacement recommendations from indirect package-only evidence. 3. Check the known families below. The presence of one package from a family is fine; only consider replacement when multiple packages from the same family are present. 4. After known-family checks, inspect the direct dependency list for other potentially similar packages not listed below. Treat these as candidates only when package purpose overlaps clearly; avoid speculative replacement advice. 5. Use packages similar or query packages_similar as an additional signal, not the only source of evidence.

Similar package families:

1. lodash, lodash-es

• Consider migrating from lodash to lodash-es for better tree-shaking support when both are present.

2. dayjs, moment, date-fns, js-joda

• Consider replacing moment with dayjs for smaller bundle size when both are present and project requirements allow it.

3. antd, material-ui, semantic-ui-react, arco-design 4. axios, node-fetch 5. redux, mobx, zustand, recoil, jotai 6. chalk, colors, picocolors, kleur 7. fs-extra, graceful-fs

If there are no similar packages, simply say there are no similar packages. Do not list packages that merely exist in the project.

Keep the response simple: name only coexisting known-family packages or other direct-dependency candidates with clear overlap, explain why coexistence is worth reviewing, and give one replacement direction if the evidence supports it.

Media Asset Analysis

Use assets media or bundle optimize when checking oversized image, font, or video assets. Return recommendations only for assets that are actually oversized or relevant to the user's question.

Image thresholds:

• Mobile: one image file should ideally be under 60 KB; Base64 SVG should ideally be under 7 KB.
• PC: one image file should ideally be under 200 KB; Base64 SVG should ideally be under 20 KB.

Image recommendations:

• Compress large images with image compression tools such as @rsbuild/plugin-image-compress (svgo for SVG and @napi-rs/image for other images).
• Optimize SVG paths with tools such as SVGO.
• Consider whether SVG is necessary for the asset.
• Choose formats by compression characteristics:
• PNG works best for images with few colors and sharp boundaries, such as text or simple patterns.
• JPG works best for natural images with gradients and irregular transitions, such as landscapes and portraits.
• Base64 is suitable for important small images that should avoid extra requests and render immediately. Base64 increases binary size by about one third, but after gzip the increase is usually no more than about 10%.

Font thresholds:

• Prefer .woff2.
• Keep a single font file under 100 KB when possible.
• Keep total font size under 300 KB for the page, and under 200 KB for mobile when possible.
• Avoid font formats other than ttf, woff, and woff2 unless there is a compatibility requirement.

Font recommendations:

• Prefer system fonts when custom fonts are not required.
• Use font-display: swap or @font-face unicode-range for more efficient loading.
• Ensure server-side Gzip or Brotli compression is enabled.
• Consider variable fonts when they replace multiple weight or width files.

Video thresholds:

• Keep a single video file under 500 KB when possible.
• Keep total video resources loaded on a page under 1 MB when possible.

Video recommendations:

• Compress video files with tools such as HandBrake or FFmpeg.
• Use MP4 (H.264) as the compatibility default.
• Use WebM (VP9) when modern-browser compression benefits justify it.
• Lazy-load non-critical videos.
• Use HLS or DASH for long videos.
• Remove unused videos.
• Tune preload:
• none: do not download until playback starts; useful for videos unlikely to be played.
• metadata: downloads metadata only, often around 3% of file size.
• auto: downloads the full video; use only when playback is very likely.

Bundle Optimize

Use bundle optimize / build optimize as an aggregate optimization pass. It can combine evidence from:

• Duplicate package rules (getRuleInfo / errors list / rule details).
• Similar package checks (packages similar / query packages_similar).
• Media asset checks (assets media).
• Chunk checks (chunks list, chunks large, or chunk details) for oversized resources and splitChunks recommendations.

Do not run bundle optimize / build optimize in the default analysis path. Use it only for a user-requested optimization deep dive or when the compact default evidence set is missing required fields.

When using it, keep output compact with --compact, narrow --filter fields, and pagination options such as --side-effects-page-size 10. If the command still returns thousands of lines, stop and switch to narrower supporting commands.

Do not treat aggregate output as enough by itself when the recommendation needs concrete evidence. Fetch the narrow supporting data before recommending a config or dependency change.

Build Performance

Use these as short recommendation candidates when Rsdoctor evidence points to build-time cost, loader cost, too many modules, or slow dev rebuilds. Source: Rsbuild build performance guide.

• Start with build performance analysis. Use measured bottlenecks before recommending config changes. Use Rsdoctor loader costs data.
• General improvements: upgrade Rsbuild, enable performance.buildCache for faster rebuilds, reduce module count, and keep Tailwind CSS v3 content narrow and correct.
• Tooling choices: prefer SWC over Babel transforms, avoid Less-heavy pipelines when possible, and prefer faster minification such as Rsbuild/Rspack SWC minification over Terser when compatible.
• Sass handling: do not send already-built node_modules/**/*.css through sass-loader; prefer third-party dist/*.css outputs when available. Compile third-party .scss / .sass only when Sass source features are required, such as variables, mixins, functions, or theme customization, and use an allowlist for those packages instead of all node_modules.
• Less projects: if many Less files are present, consider @rsbuild/plugin-less parallel compilation.
• Development mode: consider dev.lazyCompilation, Rspack experiments.nativeWatcher, cheaper or disabled dev source maps, and a narrower development Browserslist.
• Rsdoctor loader evidence: if sass-loader time is concentrated in third-party package directories and those packages ship CSS artifacts, recommend importing the CSS artifact or narrowing Sass rule include to app source plus specific allowlisted theme packages.
• Call out tradeoffs: development Browserslist and source map changes can make dev output differ from production or reduce debugging detail.

Retained Module Tree-shaking Analysis

Use tree-shaking retained-modules for first-pass tree-shaking evidence when the goal is to find retained emitted modules by reason category. Prefer it over broad tree-shaking summary when the user asks for top retained modules, CommonJS retention, barrel imports, side effects, or gzip-size priority.

Recommended first-pass command shape:

rsdoctor-agent tree-shaking retained-modules \
  --data-file dist/rsdoctor-data.json \
  --emitted-only \
  --category cjs,barrel,side-effects \
  --sort gzipSize \
  --limit 10 \
  --filter id,path,packageName,version,category,size,chunks,bailoutReason,recommendation

Guidance:

1. Keep --emitted-only by default so findings map to shipped bundle impact. 2. Use --category cjs,barrel,side-effects for optimization scans; narrow --category when the user asks about one class. 3. Sort by gzipSize for bundle impact, unless the user asks for source or parsed size. 4. Keep --limit bounded. Use --limit 10 for default analysis. Increase to 50 only for user-requested deep dives. 5. Do not add --compact; tree-shaking retained-modules output size is controlled with --limit and --filter. 6. Report rows as Path | Package | Category | Gzip/Parsed Size | Chunks | Bailout | Recommendation. 7. Treat results as first-pass evidence. Use modules issuer only after the user asks to trace who imported a retained module.

Common Questions

Why is a module not tree-shaken?

Example: "Why is node_modules/rc-tree/lib/util.js not tree-shaken?"

• Start with tree-shaking retained-modules filtered to id, path, package, category, size, chunks, bailout reason, and recommendation when the module appears in emitted output.
• Use tree-shaking summary only when retained modules do not include the needed field or the question needs broader aggregate context.
• Return the module's bailoutReason.
• Explain the bailout in plain language.
• Show issuerPath only when the user asks for chain tracing or when it is necessary to explain the issue.

Who imported a module?

Example: "Who imported lodash-es/constant.js?"

• Use module lookup by path, then issuer/import-chain data.
• Show the dependency chain using arrow notation or a tree.

Show modules with side effects

Example: "Show all modules with side effects."

• Prefer tree-shaking retained-modules --emitted-only --category side-effects for emitted side-effect modules.
• Fall back to tree-shaking summary or the relevant module-side-effects command only when retained-module output is insufficient.
• Filter to module id, path, package, size, chunks, bailout reason, and recommendation.
• List modules with non-empty bailoutReason containing side_effects.
• Use --limit 10 for default output. Increase only after user confirmation.
• If falling back to tree-shaking summary or modules side-effects, use --page-size 10 or --side-effects-page-size 10, keep the same narrow fields, and stop expanding when one command exceeds 5k tokens or 500 KB raw output.
• Sort by size, give priority to the largest emitted modules.

Why is a package duplicated?

Example: "Why is package X duplicated?"

• Use duplicate package rule data (E1001 / E1002) and package graph fields.
• Show which chunks and modules contain the duplicate versions.
• Explain the dependency path if the user asks to continue chain tracing.

Which modules are not tree-shaken because of side effects?

• Use the E1007 rule results directly to identify modules that are not tree-shaken due to side effects. By tree-shaking summary.
• If further details are needed, you may also use tree-shaking retained-modules --emitted-only --category side-effects and filter to module id, path, package, size, chunks, bailout reason, and recommendation.
• List modules with bailoutReason containing side_effects.
• Use --limit 10 by default and the same 5k token / 500 KB raw-output stop rule for fallback commands.
• Show issuerPath when needed to identify the import source.

Output Style

• For dependency chains, use a tree or arrow notation.
• For module details, use a table or key-value list.
• For explanations, use concise, plain language.
• Avoid listing all packages or assets when the finding is empty.

Common Steps for Rsdoctor Installation

This document contains common steps that apply to both Rspack and Webpack projects.

Step 3: Locate the rsdoctor-data.json

First, use the fast path to check whether rsdoctor-data.json already exists. If the user provided a path, check that path first. Otherwise check common build artifact/output locations before any package-manager, install, config, or build command:

• dist/rsdoctor-data.json (most common)
• output/rsdoctor-data.json
• static/rsdoctor-data.json
• .rsdoctor/rsdoctor-data.json (if using custom reportDir)

If common paths do not contain the file, run one bounded local file search that excludes expensive directories, for example rg --files -g 'rsdoctor-data.json' -g '!node_modules' -g '!**/.git/**'. If rsdoctor-data.json is found, skip the generation/version gate and go directly to JSON analysis. If it is not found, do not run any rsdoctor-agent analysis command; ask for the data path or generate the file first.

For repeated analysis in the same repository, use a lightweight project-local cache such as .rsdoctor-analysis-cache.json. Reuse it only when the cached data-file path still exists and cached modification times match the current rsdoctor-data.json, dependency files (package.json, lock files), relevant build config files, and plugin package.json if recorded. Refresh the cache after locating a new data file or confirming a plugin version.

When the runtime supports parallel execution, run independent local initialization checks concurrently: common path checks, bounded rg --files lookup, and local plugin-version file reads. Do not run rsdoctor-agent CLI checks until a real rsdoctor-data.json path exists. Treat plugin-version results as speculative until the data file is confirmed missing; never let parallel plugin checks trigger generation by themselves.

If you cannot find the file, ask the user to provide the path to rsdoctor-data.json. If the file truly does not exist and generation/setup is required, check the installed @rsdoctor/rspack-plugin or @rsdoctor/webpack-plugin version before changing config or running a build. The @rsdoctor/agent-cli version does not prove plugin support for RSDOCTOR_OUTPUT=json.

Required version gate (use exactly this if/else order):

1. Identify pluginName: @rsdoctor/rspack-plugin or @rsdoctor/webpack-plugin. 2. Determine pluginVersion from local files first: dependency declarations in package.json, lockfile entries, then installed node_modules/<plugin>/package.json. Use package-manager output such as pnpm why @rsdoctor/rspack-plugin / npm ls @rsdoctor/rspack-plugin only as a fallback. 3. Choose one branch; do not merge branches:

if pluginName is missing:
  install/register the matching Rsdoctor plugin, then MUST 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, MUST 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 versions, a command such as RSDOCTOR_OUTPUT=json RSDOCTOR=true pnpm run build:rspack is incorrect.

The file is typically generated in the same directory as your build output (e.g., dist, output, static). For plugin versions < 1.5.11, configure a custom output directory using the output.reportDir option:

// Example for Rspack: use RsdoctorRspackPlugin
// Example for Webpack: use RsdoctorWebpackPlugin
new RsdoctorRspackPlugin({
  // or RsdoctorWebpackPlugin
  disableClientServer: true,
  output: {
    mode: 'brief',
    options: {
      type: ['json'],
    },
    reportDir: './dist', // Custom output directory (defaults to build output directory)
  },
});

---

Step 4: Use JSON file for analysis

Once you have the rsdoctor-data.json file, you can use it for analysis. This JSON file contains all the build analysis data and can be used without starting the Rsdoctor server.

Analyze the JSON file with the rsdoctor-agent CLI from the repository root or another directory that can access the JSON file:

rsdoctor-agent build summary --data-file ./dist/rsdoctor-data.json --filter "<fields>"

Keep analysis output small:

• Reuse already returned results from context/history first, then run only missing queries.
• Use --filter on data-fetch commands to return only fields required for the current question.
• Use first-pass summaries for duplicate packages and tree-shaking issues; ask before continuing reference-chain tracing.
• Stop broad commands when one response exceeds 5k tokens (o200k_base) or 500 KB raw output, then switch to filtered or targeted queries.

For command names, option scopes, tree-shaking command selection, and --filter guidance, use command-map.md. For raw data field names, use rsdoctor-data-types.md.

Benefits of JSON Mode:

• ✅ No need to keep the build process running
• ✅ Works in CI/CD environments
• ✅ Can be shared and version controlled
• ✅ Faster analysis for large projects
• ✅ No server connection required

Note: rsdoctor-data.json can be large in complex projects. Add it to .gitignore if you do not want to commit it.

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.

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:

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:

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 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`:

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`:

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).

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:

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:

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:

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 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).

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
• For Webpack projects: See 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
• If project uses Webpack (webpack >= 5) → Use projectType: 'webpack' → See install-rsdoctor-webpack.md

2. Check framework (framework):

• If using Rspack CLI → framework: 'rspack' → See install-rsdoctor-rspack.md
• If using Rsbuild → framework: 'rsbuild' → See install-rsdoctor-rspack.md
• If using Modern.js → framework: 'modern.js' → See install-rsdoctor-rspack.md
• If using Rslib → framework: 'rslib' → See install-rsdoctor-rspack.md
• If using Rspress → framework: 'rspress' → See install-rsdoctor-rspack.md
• If using Webpack → framework: 'webpack' → See 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

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:

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.

npm view @rsdoctor/types version dist.tarball --json

If command execution is unavailable, use the registry endpoint directly:

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:

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.