#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 to let a coding agent inspect your project, apply the relevant migration steps, and verify the result:

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:

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:

import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

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:

pnpm add -D @rsdoctor/core @rsdoctor/cli

The command names and Node.js API remain available. See the CLI tutorial 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:

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:

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

#Configuration change details

#mode

The top-level mode option was removed in Rsdoctor 2.x. Use output.mode to keep output-related settings together.

new RsdoctorRspackPlugin({
  mode: 'normal',
});

new RsdoctorRspackPlugin({
  output: {
    mode: 'normal',
  },
});

#port

The top-level port option was removed in Rsdoctor 2.x. Move the port configuration to server.port.

new RsdoctorRspackPlugin({
  port: 3001,
});

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.

new RsdoctorRspackPlugin({
  mode: 'brief',
  brief: {
    reportHtmlName: 'build-report.html',
  },
});

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'].

new RsdoctorRspackPlugin({
  output: {
    compressData: true,
  },
});

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.

new RsdoctorRspackPlugin({
  mode: 'lite',
});

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 for the available fields.

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:

   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.