# Migrate from webpack to Rspack

This guide explains how to move the frontend build of your plugin from webpack to [Rspack](https://rspack.rs) 2 with the `rspack` addition of the `create-plugin` tool. It also applies to plugins that use the experimental Rspack setup from earlier versions of `create-plugin`.

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

* Commit or stash your changes. The `add` command stops if the repository has uncommitted changes.
* Use Node.js 22.23 or later. The migration raises `engines.node` in your `package.json` file to `>=22.23` if it allows an older version.

## Run the migration[​](#run-the-migration "Direct link to Run the migration")

From the root of your plugin, run the `rspack` addition:

* npm
* Yarn
* pnpm

```shell
npx @grafana/create-plugin@latest add rspack

```

```shell
yarn dlx @grafana/create-plugin@latest add rspack

```

```shell
pnpm dlx @grafana/create-plugin@latest add rspack

```

If you have Claude Code or OpenAI Codex installed, `create-plugin` asks whether to use it. The agent ports any custom build configuration in your project root to `rspack.config.ts`. When it finishes, `create-plugin` runs your `typecheck` and `build` scripts and lists anything the agent marked with a `TODO(rspack):` comment. Review the changes with `git diff` before you commit them.

To learn how agents work with the `add` command, refer to [Add features to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/add-features-to-a-plugin.md). If you don't have an agent, or prefer to port the configuration yourself, refer to [Migrate without an agent](#migrate-without-an-agent).

info

To have your own coding agent run the migration, give it this prompt:

```text
Run `npx @grafana/create-plugin@latest add rspack` and follow its instructions. Don't commit.

```

## What changes in your project[​](#what-changes-in-your-project "Direct link to What changes in your project")

The migration changes these files:

* `.config/rspack/`: adds the Rspack base configuration.

* `.config/webpack/`: removes the files that `create-plugin` added. The migration keeps any files of your own in this folder and lists them in the command output.

* `.config/bundler/`: updates the helpers that the base configuration uses.

* `package.json`:

  <!-- -->

  * Adds the Rspack packages and removes the packages that only the webpack base configuration used. A package stays if a `webpack.*` or `rspack.*` file in the project root still imports it. The `webpack` package always stays, because `diagnostics-webpack-plugin`, which lints your code during development, depends on it.
  * Replaces `webpack` with `rspack` in your scripts. The command output lists any script it can't rewrite.
  * Raises `engines.node` to `>=22.23`, if it allows an older version.

* `src/plugin.json`: raises `grafanaDependency` to `>=12.2.5`, if it allows an older version. Earlier versions of Grafana don't provide `react/jsx-runtime`, which the Rspack configuration loads from Grafana.

* `.config/.cprc.json`: sets the `useRspack` feature flag, so that later `create-plugin update` runs treat your plugin as an Rspack plugin.

The Rspack configuration builds the CSS your entry code imports into a `module.css` file next to `module.js`, and Grafana loads it before your plugin code runs. CSS that only lazy-loaded code imports goes into separate files that load with that code, and CSS that several lazy-loaded parts share goes into one file. If your plugin imports no CSS, it has no CSS files. The CSS changes in these ways:

* Files named `*.module.css` or `*.module.scss` are CSS modules. Their class names start with your plugin ID, so they don't clash with other plugins.
* Other CSS files apply to the whole Grafana page, as before.
* All of the plugin's CSS is in a cascade layer, so Grafana's own styles win over plugin styles of equal specificity.

If your plugin uses the experimental Rspack setup, the migration replaces the files in `.config/rspack/` with the Rspack 2 base configuration and upgrades the Rspack packages. If you run `create-plugin update` before the migration, it only renames the `useExperimentalRspack` feature flag to `useRspack`.

## Migrate without an agent[​](#migrate-without-an-agent "Direct link to Migrate without an agent")

To make the changes without an agent, run the addition with the `--no-agent` flag:

* npm
* Yarn
* pnpm

```shell
npx @grafana/create-plugin@latest add rspack --no-agent

```

```shell
yarn dlx @grafana/create-plugin@latest add rspack --no-agent

```

```shell
pnpm dlx @grafana/create-plugin@latest add rspack --no-agent

```

The command makes the changes listed in [What changes in your project](#what-changes-in-your-project), then prints the path to an instructions file. If your plugin has no `webpack.config.*` or `rspack.config.*` file in the project root, the migration is complete. Otherwise, update that file as described in the following sections.

### Port a webpack configuration[​](#port-a-webpack-configuration "Direct link to Port a webpack configuration")

If your plugin has a `webpack.config.*` file in the project root, the migration adds an `rspack.config.ts` file that stops the build with an error like this:

```text
[rspack] webpack.config.ts has not been ported to rspack.config.ts yet.

```

The error prevents you from releasing a build without your customizations. To port your configuration:

1. Merge your customizations into the base configuration in `rspack.config.ts` with [`rspack-merge`](https://github.com/rstackjs/rspack-merge):

   rspack.config.ts

   ```ts
   import type { Configuration } from '@rspack/core';
   import { merge } from 'rspack-merge';
   import grafanaConfig, { type Env } from './.config/rspack/rspack.config.ts';

   const config = async (env: Env): Promise<Configuration> => {
     const baseConfig = await grafanaConfig(env);

     return merge(baseConfig, {
       // your customizations
     });
   };

   export default config;

   ```

2. Replace webpack plugins and loaders with their Rspack equivalents. For example, replace `copy-webpack-plugin` with `CopyRspackPlugin` from `@rspack/core`. For the full list, refer to [Migrate from webpack](https://rspack.rs/guide/migration/webpack) in the Rspack documentation.

3. Make the file work as a native ECMAScript module (ESM), because the Rspack CLI loads it that way. Replace `__dirname` with `import.meta.dirname` and `require()` with `import`, and add the `.ts` extension to relative imports.

4. Comment out any code that has no Rspack equivalent, and add a `TODO(rspack):` comment that explains what the code did.

5. Remove the `[rspack]` error.

6. Delete the `webpack.config.*` file and any files that only it imports.

The instructions file that the command prints covers more cases than this guide, such as configurations that look up base rules by loader name.

### Upgrade an experimental Rspack configuration[​](#upgrade-an-experimental-rspack-configuration "Direct link to Upgrade an experimental Rspack configuration")

The migration doesn't change the `rspack.config.ts` file in your project root. Update that file for the changes listed in [Migrate from Rspack 1.x](https://rspack.rs/guide/migration/rspack_1.x), and replace `webpack-merge` with `rspack-merge`.

## Check the result[​](#check-the-result "Direct link to Check the result")

Run your checks and start the development build:

* npm
* Yarn
* pnpm

```shell
npm run typecheck
npm run build
npm run dev

```

```shell
yarn typecheck
yarn build
yarn dev

```

```shell
pnpm run typecheck
pnpm run build
pnpm run dev

```

After the build, check that `dist/` contains `module.js`, `plugin.json`, and any file that your plugin refers to by path at runtime.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### The build fails with an `[rspack]` error[​](#the-build-fails-with-an-rspack-error "Direct link to the-build-fails-with-an-rspack-error")

The build configuration in your project root isn't ported yet. Refer to [Port a webpack configuration](#port-a-webpack-configuration).

### `ReferenceError: __dirname is not defined`[​](#referenceerror-__dirname-is-not-defined "Direct link to referenceerror-__dirname-is-not-defined")

`rspack.config.ts`, or a file it imports, uses a CommonJS global. Replace `__dirname` with `import.meta.dirname`.

### The build fails because an export doesn't exist[​](#the-build-fails-because-an-export-doesnt-exist "Direct link to The build fails because an export doesn't exist")

Rspack 2 stops the build when code imports a name that a module doesn't export. In webpack, this was a warning. Fix the import in your code.

### A style no longer applies[​](#a-style-no-longer-applies "Direct link to A style no longer applies")

The plugin's CSS is in a cascade layer, so a Grafana style with the same specificity now wins over it. Make your selector more specific, or style the element with a CSS module or with the `useStyles2` hook from `@grafana/ui`.

An `@import` rule that loads a style sheet from another URL, such as a web font service, doesn't apply either. Add the files to your plugin and import them from your code instead.

### A file returns 404 at runtime[​](#a-file-returns-404-at-runtime "Direct link to A file returns 404 at runtime")

Base configurations from older versions of `create-plugin` copied images, SVG and HTML files, and the `img/`, `libs/` and `static/` folders, into `dist/`. The current base configuration copies only `plugin.json` and other JSON files, the README, CHANGELOG and LICENSE files, `query_help.md`, and the logos and screenshots that `plugin.json` lists. If you created your plugin with an older version, the migration brings in this change.

If your code builds a URL to any other file, import the file and use the imported URL instead:

```tsx
import howItWorks from '../img/how-it-works.svg';

export const HowItWorks = () => <img src={howItWorks} alt="How it works" />;

```

If your code builds the path at runtime, add a `CopyRspackPlugin` to `rspack.config.ts` for those files.

## Next steps[​](#next-steps "Direct link to Next steps")

* To extend the Rspack configuration later, follow the steps in the `.config/README.md` file of your plugin.
* To learn more about additions and the `add` command, refer to [Add features to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/add-features-to-a-plugin.md).
