@nx/rsbuild - Migrations

For an overview of the plugin and setup instructions, see the @nx/rsbuild introduction.

The @nx/rsbuild plugin provides various migrations to help you migrate to newer versions of rsbuild projects within your Nx workspace. Below is a complete reference for all available migrations.

24.0.x

update-24-0-0-register-typescript-plugin-for-typecheck

Version: 24.0.0-beta.3

Register @nx/js/typescript with its typecheck target in workspaces that use @nx/rsbuild without it, and remove the typecheckTargetName option from @nx/rsbuild, since @nx/rsbuild no longer infers typecheck targets.

Register @nx/js/typescript for typecheck targets

@nx/rsbuild no longer infers a typecheck target in any setup, and @nx/js/typescript provides it instead. This migration registers @nx/js/typescript with only its typecheck target when the workspace uses @nx/rsbuild and doesn’t register @nx/js/typescript yet, so your projects keep a typecheck target.

The new registration is added before the framework plugin and reuses its typecheckTargetName, and the migration removes that option from the @nx/rsbuild registration. Registrations with typecheckTargetName: false lose the option without registering @nx/js/typescript.

Sample code changes

Before

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/rsbuild",
      "options": {
        "buildTargetName": "build",
        "typecheckTargetName": "typecheck"
      }
    }
  ]
}

After

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "options": { "typecheck": { "targetName": "typecheck" } }
    },
    {
      "plugin": "@nx/rsbuild",
      "options": {
        "buildTargetName": "build"
      }
    }
  ]
}

update-24-0-0-add-ready-signal-plugin

Version: 24.0.0-beta.5

Adds pluginNxReadySignal() from @nx/rsbuild/ready-signal to existing Rsbuild configs so the inferred dev and preview targets report readiness once the server listens. Configs the generator cannot edit safely are completed by an AI prompt.

Add the Nx ready-signal plugin to Rsbuild configs

The dev and preview targets that @nx/rsbuild infers carry a readyWhen check, so a dependent task can wait until the server accepts requests. With pluginNxReadySignal() in the Rsbuild config, the server reports its address to Nx as soon as it listens, and the targets are inferred with readyWhen: { "signal": true }. Without it, Nx loads the config when the task runs and waits for the configured port instead.

New configs include the plugin. This migration adds it to each project’s existing rsbuild.config.{ts,mts,cts,js,mjs,cjs} when the file calls defineConfig once with an object literal, or a function with a single return of one, whose plugins option is missing or a literal array. Configs that already reference the plugin are left alone.

Configs the migration can’t edit safely stay untouched and are listed with the reason. That includes CommonJS modules, mergeRsbuildConfig, a spread into the config or its plugins array, a plugins value that isn’t an array literal, a config factory without a single top-level return, and files with syntax errors. In an agentic run, an AI step adds the plugin to those.

Sample code changes

Before

apps/app1/rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    port: 4200,
  },
});

After

apps/app1/rsbuild.config.ts

import { pluginNxReadySignal } from '@nx/rsbuild/ready-signal';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [pluginReact(), pluginNxReadySignal()],
  server: {
    port: 4200,
  },
});

23.1.x

update-23-0-0-migrate-rsbuild-config-to-v2

Version: 23.1.0-beta.0

Rewrites rsbuild.config.{js,ts,mjs,cjs} files for @rsbuild/core@2: renames preview.setupMiddlewares to server.setupMiddlewares, drops the removed performance.removeMomentLocale option, moves source.alias/source.aliasStrategy to the resolve block, and updates server.proxy entries for http-proxy-middleware v4 (context to pathFilter, on* handlers to a unified on object).

Requires

Name	Version
@rsbuild/core	>=2.0.0

update-23-0-0-migrate-node-output-to-esm

Version: 23.1.0-beta.0

AI-assisted migration: make Node-target rsbuild builds runnable under @rsbuild/core@2, which emits ESM output by default.

Requires

Name	Version
@rsbuild/core	>=2.0.0

update-23-0-0-migrate-performance-options

Version: 23.1.0-beta.0

AI-assisted migration: adopt replacements for the performance.bundleAnalyze and performance.profile options removed in @rsbuild/core@2, and migrate the deprecated performance.chunkSplit option to splitChunks.

Requires

Name	Version
@rsbuild/core	>=2.0.0

23.0.0-rsbuild-v2-package-updates

Version: 23.1.0-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@rsbuild/core	^2.0.7	Updated only
@rsbuild/plugin-react	^2.0.0	Updated only
@rsbuild/plugin-sass	^1.5.2	Updated only

23.0.x

update-23-0-0-migrate-create-nodes-v2-import

Version: 23.0.0-beta.24

Rename imports of createNodesV2 from @nx/rsbuild to the canonical createNodes export.

Rename createNodesV2 imports to createNodes

@nx/rsbuild renamed its primary inferred-plugin export from createNodesV2 to createNodes. The createNodesV2 name is preserved as a deprecated alias for now, but new code should use createNodes.

This migration scans every .ts, .tsx, .cts, and .mts file in your workspace and rewrites named imports and re-exports of createNodesV2 from @nx/rsbuild to createNodes.

Sample Code Changes

Before

import { createNodesV2 } from '@nx/rsbuild';

After

import { createNodes } from '@nx/rsbuild';

Aliases are preserved (createNodesV2 as cn becomes createNodes as cn), and if a file already imports both names ({ createNodes, createNodesV2 }) the redundant binding is dropped.

What is not rewritten

Only static import/export named bindings from @nx/rsbuild are rewritten. Namespace imports, dynamic import(...), require(...) destructuring, and property access such as plugin.createNodesV2 are left untouched — they keep working through the createNodesV2 runtime alias. Update those by hand if you want to drop the deprecated name everywhere.