close
Guide
Config
Plugin
API
Community
Version
Guide
Config
Plugin
API
Community

Vite plugin

This chapter introduces how to migrate a Vite plugin to Rsbuild plugin.

Existing plugins

Before migrating a Vite plugin, it is recommended to check if there is a corresponding plugin in the Rsbuild ecosystem. You can find the plugins through the following pages:

Define a plugin

Rsbuild plugin is defined in a way similar to Vite, usually a function that accepts plugin options as a parameter and returns a plugin description object.

The main difference is that Vite's hooks are defined directly on the plugin description object, while Rsbuild's hooks are accessed and called through the api object. This allows you to control the timing of plugin API calls more flexibly.

  • Vite plugin:
vitePlugin.ts
const vitePlugin = (options) => ({
  name: 'vite-plugin',
  transform() {
    // ...
  },
});
  • Rsbuild plugin:
rsbuildPlugin.ts
const rsbuildPlugin = (options) => ({
  name: 'rsbuild-plugin',
  setup(api) {
    api.transform(() => {
      // ...
    });
  },
});

Plugin hooks

Rsbuild's plugin API covers most of the Vite and Rollup plugin hooks, for example:

Vite plugin hooksRsbuild plugin API
resolveIdresolve
transformtransform
configmodifyRsbuildConfig
configResolvedgetNormalizedConfig
configEnvironmentmodifyEnvironmentConfig
configureServeronBeforeStartDevServer
buildStartonBeforeBuild, onBeforeStartDevServer
buildEndonAfterBuild, onCloseDevServer
closeBundleonCloseBuild, onCloseDevServer
transformIndexHtmlmodifyHTML, modifyHTMLTags

See Plugin system for more details.

config hook

Rsbuild provides the modifyRsbuildConfig hook to modify Rsbuild configuration. Since Rsbuild and Vite have different configuration structures, you'll need to adjust your configuration when migrating Vite plugins.

For example, you should replace Vite's define option with Rsbuild's source.define option.

  • Vite plugin:
vitePlugin.ts
const vitePlugin = {
  name: 'my-plugin',
  config: (config) => {
    config.define = {
      ...config.define,
      FOO: '"foo"',
    };
  },
};
  • Rsbuild plugin:
rsbuildPlugin.ts
const rsbuildPlugin = {
  name: 'my-plugin',
  setup(api) {
    api.modifyRsbuildConfig((config) => {
      config.source ||= {};
      config.source.define = {
        ...config.source.define,
        FOO: '"foo"',
      };
    });
  },
};
TIP

See Config migration to learn how to migrate Vite configurations to Rsbuild.

configEnvironment hook

Rsbuild provides the modifyEnvironmentConfig hook to modify the configuration of a specific environment.

  • Vite plugin:
const vitePlugin = {
  name: 'config-environment',
  configEnvironment(name, config) {
    if (name === 'web') {
      config.resolve.alias = {
        // ...
      };
    }
  },
};
  • Rsbuild plugin:
const rsbuildPlugin = {
  name: 'config-environment',
  setup(api) {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name === 'web') {
        config.resolve.alias = {
          // ...
        };
      }
    });
  },
};

configResolved hook

Rsbuild provides the api.getNormalizedConfig method to get the resolved configuration. This method serves a similar purpose to Vite's configResolved hook.

  • Vite plugin:
vitePlugin.ts
const vitePlugin = () => {
  let config;
  return {
    name: 'read-config',
    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },
    transform() {
      console.log(config);
      // ...
    },
  };
};
  • Rsbuild plugin:
rsbuildPlugin.ts
const rsbuildPlugin = () => ({
  name: 'read-config',
  setup(api) {
    api.transform(() => {
      const config = api.getNormalizedConfig();
      console.log(config);
      // ...
    });
  },
});

transformIndexHtml hook

Vite's transformIndexHtml hook corresponds to two hooks in Rsbuild:

Here's an example of replacing the HTML title.

  • Vite Plugin:
vitePlugin.ts
const htmlPlugin = () => {
  return {
    name: 'html-plugin',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    },
  };
};
  • Rsbuild Plugin:
rsbuildPlugin.ts
const rsbuildPlugin = {
  name: 'html-plugin',
  setup(api) {
    api.modifyHTML((html) => {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    });
  },
};

configureServer hook

Rsbuild provides the onBeforeStartDevServer hook to replace Vite's configureServer hook, which allows you to get the dev server instance and add custom middleware.

  • Vite plugin:
vitePlugin.ts
const vitePlugin = () => ({
  name: 'setup-middleware',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      // custom handle request...
    });
  },
});
  • Rsbuild plugin:
rsbuildPlugin.ts
const rsbuildPlugin = {
  name: 'setup-middleware',
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      });
    });
  },
};

apply property

Rsbuild plugin provides the same apply property as Vite plugins.

  • Vite plugin:
vitePlugin.ts
const vitePlugin = {
  name: 'vite-plugin',
  apply: 'build',
};
  • Rsbuild plugin:
rsbuildPlugin.ts
const rsbuildPlugin = {
  name: 'rsbuild-plugin',
  apply: 'build',
};