Nx with Rspack

Rspack is a Rust-based JavaScript bundler with a webpack-compatible API, built as a drop-in replacement for webpack with much faster builds. Teams with existing webpack configurations get that speedup without rewriting their setup. The @nx/rspack plugin adds caching, affected builds, and task inference so Rspack scales across a monorepo.

What is Rspack?

Rspack is a bundler written in Rust that implements the webpack API. Per the Rspack team's benchmarks (as of Rspack 2), it builds and serves projects several times faster than webpack. In a monorepo those savings compound, and Nx layers caching and affected-only builds on top so unchanged projects don't build at all.

Is Rspack a drop-in replacement for webpack?

Mostly - existing loaders and the majority of webpack plugins run unchanged, so many configurations migrate with few or no edits. Plugins that depend on webpack internals may not work, so test complex setups when you migrate.

Requirements

The @nx/rspack plugin supports Rspack 1 and 2 (as of Nx v23).

Package	Supported Versions	Default Installed
@rspack/core	^1.0.0 || ^2.0.0	2.0.4

Nx generators install the latest supported version automatically when scaffolding new projects. When @rspack/core is already installed in your workspace, generators detect the installed version and keep it in place rather than overwriting it.

Setting up @nx/rspack

Installation

Keep Nx Package Versions In Sync

Make sure to install the @nx/rspack version that matches the version of nx in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can fix Nx version mismatches with this recipe.

In any Nx workspace, you can install @nx/rspack by running the following command:

nx add @nx/rspack

This will install the correct version of @nx/rspack.

How @nx/rspack infers tasks

The @nx/rspack plugin will create a task for any project that has a Rspack configuration file present. Any of the following files will be recognized as a Rspack configuration file:

• rspack.config.js
• rspack.config.ts
• rspack.config.mjs
• rspack.config.mts
• rspack.config.cjs
• rspack.config.cts

View inferred tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/rspack configuration

The @nx/rspack/plugin is configured in the plugins array in nx.json.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/rspack/plugin",
      "options": {
        "buildTargetName": "build",
        "previewTargetName": "preview",
        "serveTargetName": "serve",
        "serveStaticTargetName": "serve-static",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}

Option	Default	Inferred behavior
buildTargetName	build	Runs and caches rspack build with its configured outputs.
serveTargetName	serve	Runs rspack serve continuously in development mode.
previewTargetName	preview	Runs rspack serve continuously in production mode.
serveStaticTargetName	serve-static	Serves the build output continuously after the build task.
buildDepsTargetName	none	Name of an optional dependency build task.
watchDepsTargetName	none	Name of an optional dependency watch task.

The build task depends on builds of project dependencies. When TypeScript project references are enabled, the tasks also run the TypeScript sync generator.

Use include and exclude glob patterns on the plugin entry to scope inference. A target defaults plugin filter must use the exact identifier @nx/rspack/plugin.

Wait for the dev server to be ready

The inferred serve and preview targets come with a readyWhen check, so a task can wait until the dev server accepts requests instead of only until it has started. When the Rspack config sets devServer and loads NxAppRspackPlugin, the check waits for the plugin to report the server's address once it listens. Angular Rspack configs made with createConfig from @nx/angular-rspack load NgRspackPlugin, which reports it the same way. In other configs, add new NxReadySignalPlugin() from @nx/rspack/ready-signal to plugins instead. The report carries the port the server actually uses, so the check is right however the port was chosen.

In an Angular server-side rendering (SSR) app, the dev server reports once it listens, without waiting for the build. It holds requests until the build finishes. The SSR server starts only after the build, on PORT or the port its server file sets, 4000 in generated apps. A task that tests SSR on that port has to wait for it itself.

Without any of these plugins, the check reads the Rspack config when the task runs instead, in the task's environment and with its options. That covers .env files and --port or --host flags. It works out the port the way rspack serve does, from the --port flag, devServer.port, RSPACK_DEV_SERVER_BASE_PORT, or 8080, and waits for it. When the server picks its own port (a devServer.port of 0 or "auto") or listens on a socket instead of a port (devServer.ipc), there's nothing to wait for, and the target counts as ready once it has started. The serve-static target's file server reports its address once it listens.

A dependent task starts as soon as the server task has started, unless its dependsOn entry sets waitFor to ready:

apps/myapp-e2e/project.json

{
  "targets": {
    "e2e": {
      "dependsOn": [
        { "projects": "myapp", "target": "serve", "waitFor": "ready" }
      ]
    }
  }
}

The waiting task gets the server's address in the NX_READY_URL environment variable, when exactly one target it waits for reported one. A readyWhen on the target in targetDefaults or in the project configuration replaces the inferred check, and null turns it off. For the other checks, see wait for a continuous task to be ready. For signaling from your own server, see signal readiness from the task.

Using @nx/rspack

Generate a new project using Rspack

You can generate a React application that uses Rspack. The @nx/react:app generator accepts the bundler option, where you can pass rspack. This will generate a new application configured to use Rspack, and it will also install all the necessary dependencies, including the @nx/rspack plugin.

To generate a React application using Rspack, run the following:

nx g @nx/react:app my-app --bundler=rspack

Modify an existing React project to use Rspack

You can use the @nx/rspack:configuration generator to change your React project to use Rspack. This generator will modify your project's configuration to use Rspack, and it will also install all the necessary dependencies, including the @nx/rspack plugin.

You can read more about this generator on the @nx/rspack:configuration generator page.

Why use Rspack in a monorepo?

Rspack speeds up each build, and Nx cuts down how many builds run. In a monorepo with many Rspack projects:

• Caching skips builds whose inputs haven't changed, locally and in CI.
• nx affected rebuilds and retests only the projects a change touches.
• Because the API is webpack-compatible, you can migrate webpack projects to Rspack one at a time instead of converting every configuration in the repo at once.

For a complete pipeline, see Set up CI.