> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Migrate to Rsdoctor 2.0 Rsdoctor 2.0 consolidates the package structure around Rspack. This release removes several standalone packages. Update dependencies and imports together to avoid resolving a 1.x package with 2.0 code. Use the [`rsdoctor-migrate-v2` skill](https://github.com/rstackjs/agent-skills/pull/115) to let a coding agent inspect your project, apply the relevant migration steps, and verify the result: ```bash npx skills add rstackjs/agent-skills --skill rsdoctor-migrate-v2 ``` ## Check your bundler Rsdoctor 2.0 requires Node.js `^20.19.0 || >=22.12.0` and Rspack 2.0 or later. Rspack 1.x is no longer supported. webpack support and `@rsdoctor/webpack-plugin` have also been removed. - For an Rspack-based project, continue with this guide. - For a webpack project, stay on Rsdoctor 1.x or migrate the project to Rspack before upgrading Rsdoctor. ## Update the Rspack plugin Replace `@rsdoctor/rspack-plugin` with `@rsdoctor/core`: ```bash pnpm remove @rsdoctor/rspack-plugin pnpm add -D @rsdoctor/core ``` Rsdoctor 2.0 packages are ESM-only. Update the package path in the existing ESM import: ```ts title="Before" import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin'; ``` ```ts title="After" import { RsdoctorRspackPlugin } from '@rsdoctor/core'; ``` If a 1.x configuration uses CommonJS `require()`, replace it with the ESM import shown above. `@rspack/core` remains an optional peer dependency of `@rsdoctor/core`, with a minimum supported version of 2.0. Your Rspack-based build tool normally provides it. Install `@rspack/core` in projects that use Rspack directly. Rsdoctor 2.0 uses the Rsdoctor native plugin built into Rspack to collect module and chunk graphs. Remove the former `experiments.enableNativePlugin` option because this capability is now always enabled. If the build reports that `experiments.RsdoctorPlugin` is unavailable, upgrade the Rspack dependency supplied by your project or framework. ## CLI migration `@rsdoctor/cli` remains the `rsdoctor` command package. Use the same version of `@rsdoctor/cli` and `@rsdoctor/core`: ```bash pnpm add -D @rsdoctor/core @rsdoctor/cli ``` The command names and Node.js API remain available. See the [CLI tutorial](/guide/start/cli.md) for current usage. ## AI workflow migration Rsdoctor 2.0 removes `@rsdoctor/mcp-server` and no longer provides an MCP server. Migrate all Rsdoctor AI-assisted analysis workflows to `@rsdoctor/agent-cli`: ```bash pnpm remove @rsdoctor/mcp-server pnpm add -D @rsdoctor/agent-cli ``` Agent CLI is the replacement workflow, but it is not an MCP-compatible or drop-in API replacement. Complete the following changes instead of only replacing the package name: 1. Remove Rsdoctor MCP entries from configurations such as `.cursor/mcp.json` and `.vscode/mcp.json`. 2. Remove scripts or automation that start `npx @rsdoctor/mcp-server`. 3. Generate `rsdoctor-data.json`, then run Agent CLI directly against that file: ```bash rsdoctor-agent bundle optimize --data-file ./dist/rsdoctor-data.json rsdoctor-agent query packages_duplicates --data-file ./dist/rsdoctor-data.json ``` 4. Update AI agents and automation to invoke `rsdoctor-agent` and consume its structured JSON output. The Rsdoctor analysis skill can manage this workflow for supported coding agents. Agent CLI reads the data file directly, so MCP-specific options such as server ports and compiler selection no longer apply. See [AI](/guide/start/ai.md) for installation, data generation, and more command examples. ## Configuration migration **Rsdoctor 1.2.4 introduced the output configuration used by Rsdoctor 2.x.** It is easier to configure and extend than the legacy options. The top-level `mode`, `port`, and `brief` options and legacy `output.compressData` option were removed and are ignored in Rsdoctor 2.x. Use the table below to migrate these options. Both forms of the `features` lite configuration remain supported and are included only to show the equivalent `output` configuration. | Original Configuration | New Configuration | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | Configure `output.mode` instead. | | port | Configure `server.port` instead. | | brief | Configure `output.mode: 'brief'` and set `output.options.type` to `['html']`. Move `brief.reportHtmlName` to `output.options.htmlOptions.reportHtmlName`. | | output.compressData | Configure `output.mode: 'brief'` and set `output.options.type` to `['json']`. | | `mode: 'lite'` | Configure `output.mode: 'normal'` and set `output.reportCodeType` to `noCode` or `noAssetsAndModuleSource`. | | `features: { lite: true }` or `features: ['lite']` | Still supported. The equivalent `output` configuration uses `output.mode: 'normal'` and `output.reportCodeType` as above. | | None | New `output.options.jsonOptions.sections` configuration | ### Configuration change details #### mode The top-level `mode` option was removed in Rsdoctor 2.x. Use `output.mode` to keep output-related settings together. ```js title="Before" new RsdoctorRspackPlugin({ mode: 'normal', }); ``` ```js title="After" new RsdoctorRspackPlugin({ output: { mode: 'normal', }, }); ``` #### port The top-level `port` option was removed in Rsdoctor 2.x. Move the port configuration to `server.port`. ```js title="Before" new RsdoctorRspackPlugin({ port: 3001, }); ``` ```js title="After" new RsdoctorRspackPlugin({ server: { port: 3001, }, }); ``` #### brief The top-level `brief` option was removed in Rsdoctor 2.x. The current brief report mode supports both HTML and JSON output, with its configuration grouped under `output.options`. Replace the original `brief` configuration with `output.mode: 'brief'` and set `output.options.type` to `['html']`. Move `brief.reportHtmlName` to `output.options.htmlOptions.reportHtmlName`. ```js title="Before" new RsdoctorRspackPlugin({ mode: 'brief', brief: { reportHtmlName: 'build-report.html', }, }); ``` ```js title="After" new RsdoctorRspackPlugin({ output: { mode: 'brief', options: { type: ['html'], htmlOptions: { reportHtmlName: 'build-report.html', }, }, }, }); ``` #### output.compressData `output.compressData` was removed and is ignored in Rsdoctor 2.x. Replace it with `output.mode: 'brief'` and set `output.options.type` to `['json']`. ```js title="Before" new RsdoctorRspackPlugin({ output: { compressData: true, }, }); ``` ```js title="After" new RsdoctorRspackPlugin({ output: { mode: 'brief', options: { type: ['json'], }, }, }); ``` #### lite The internal logic of lite mode is equivalent to `output.reportCodeType` being `noCode` or `noAssetsAndModuleSource`, mainly to solve the problem of large projects being too slow when opening reports or OOM during build. `mode: 'lite'` was removed and is ignored in Rsdoctor 2.x. Replace it with `output.mode: 'normal'`, and set `output.reportCodeType` to `noCode` or `noAssetsAndModuleSource`. Both `features: { lite: true }` and `features: ['lite']` remain supported and do not need to be migrated. The equivalent `output.reportCodeType` configuration expresses the intended report content more clearly. ```js title="Before" new RsdoctorRspackPlugin({ mode: 'lite', }); ``` ```js title="After" new RsdoctorRspackPlugin({ output: { mode: 'normal', reportCodeType: 'noAssetsAndModuleSource', }, }); ``` #### output.options.jsonOptions.sections Use `output.options.jsonOptions.sections` to control which sections are included in JSON output. See [output.options.jsonOptions.sections](/config/options/output.md#options) for the available fields. ```js new RsdoctorRspackPlugin({ output: { mode: 'brief', options: { type: ['json'], jsonOptions: { sections: { moduleGraph: false, chunkGraph: true, }, }, }, }, }); ``` ## Verify the upgrade After updating dependencies and imports: 1. Search the application for removed package names: ```bash rg '@rsdoctor/(rspack-plugin|webpack-plugin|sdk|graph|types|utils|components|mcp-server)' ``` 2. Reinstall dependencies with the project's package manager. 3. Run the project's production build and confirm that Rsdoctor generates a report. 4. Open the report and verify the overview, compilation, and bundle analysis pages used by the project. 5. If the project uses `@rsdoctor/cli` or `@rsdoctor/agent-cli`, run the relevant command against newly generated Rsdoctor data.