close
  • English

      • 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 is 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',
};