简体中文

Vite 插件

本章节介绍如何将 Vite 插件迁移到 Rsbuild 插件。

现有插件

在迁移一个 Vite 插件之前，建议先检查 Rsbuild 生态中是否存在对应的插件，你可以通过以下页面来查找：

定义一个插件

Rsbuild 插件的定义方式与 Vite 相似，通常都是一个接收插件选项作为参数的函数，并返回插件的描述对象。

两者的主要区别在于：Vite 的 hooks 直接定义在插件描述对象上，而 Rsbuild 的 hooks 是通过 api 对象来访问和调用，这允许你更灵活地控制插件 API 的调用时机。

Vite 插件：

vitePlugin.ts

const vitePlugin = (options) => ({
  name: 'vite-plugin',
  transform() {
    // ...
  },
});

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = (options) => ({
  name: 'rsbuild-plugin',
  setup(api) {
    api.transform(() => {
      // ...
    });
  },
});

插件 hooks

Rsbuild 的插件 API 覆盖了大部分的 Vite 和 Rollup 插件 hooks，例如：

Vite 插件 hooks	Rsbuild 插件 API
`resolveId`	resolve
`transform`	transform
`config`	modifyRsbuildConfig
`configResolved`	getNormalizedConfig
`configEnvironment`	modifyEnvironmentConfig
`configureServer`	onBeforeStartDevServer
`buildStart`	onBeforeBuild, onBeforeStartDevServer
`buildEnd`	onAfterBuild, onCloseDevServer
`closeBundle`	onCloseBuild, onCloseDevServer
`transformIndexHtml`	modifyHTML, modifyHTMLTags

请参考插件系统文档来了解更多。

`config` 钩子

Rsbuild 提供了 modifyRsbuildConfig 钩子来修改 Rsbuild 配置。由于 Rsbuild 与 Vite 的配置结构存在差异，在迁移 Vite 插件时，需要对配置进行调整。

例如，需要将 Vite 的 define 选项替换为 Rsbuild 的 source.define 选项。

Vite 插件：

vitePlugin.ts

const vitePlugin = {
  name: 'my-plugin',
  config: (config) => {
    config.define = {
      ...config.define,
      FOO: '"foo"',
    };
  },
};

Rsbuild 插件：

rsbuildPlugin.ts

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

TIP

查看配置迁移了解如何将 Vite 的配置迁移到 Rsbuild。

`configEnvironment` 钩子

Rsbuild 提供了 modifyEnvironmentConfig 钩子来修改特定 environment 的配置。

Vite 插件：

const vitePlugin = {
  name: 'config-environment',
  configEnvironment(name, config) {
    if (name === 'web') {
      config.resolve.alias = {
        // ...
      };
    }
  },
};

Rsbuild 插件：

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

`configResolved` 钩子

Rsbuild 提供了 api.getNormalizedConfig 方法来获取已解析的配置。这个方法与 Vite 的 configResolved 钩子的使用场景类似。

Vite 插件：

vitePlugin.ts

const vitePlugin = () => {
  let config;
  return {
    name: 'read-config',
    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },
    transform() {
      console.log(config);
      // ...
    },
  };
};

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = () => ({
  name: 'read-config',
  setup(api) {
    api.transform(() => {
      const config = api.getNormalizedConfig();
      console.log(config);
      // ...
    });
  },
});

`transformIndexHtml` 钩子

Vite 的 transformIndexHtml 钩子对应了 Rsbuild 的两个钩子：

modifyHTML：用于修改 HTML 内容
modifyHTMLTags：用于修改 HTML 标签

下面一个是替换 HTML 标题的示例。

Vite 插件：

vitePlugin.ts

const htmlPlugin = () => {
  return {
    name: 'html-plugin',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    },
  };
};

Rsbuild 插件：

rsbuildPlugin.ts

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

`configureServer` 钩子

Rsbuild 提供了 onBeforeStartDevServer 钩子来替代 Vite 的 configureServer 钩子，它允许你获取 dev server 实例和添加自定义的中间件。

Vite 插件：

vitePlugin.ts

const vitePlugin = () => ({
  name: 'setup-middleware',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      // custom handle request...
    });
  },
});

Rsbuild 插件：

rsbuildPlugin.ts

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

`apply` 属性

Rsbuild 插件提供了与 Vite 插件一致的 apply 属性。

Vite 插件：

vitePlugin.ts

const vitePlugin = {
  name: 'vite-plugin',
  apply: 'build',
};

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = {
  name: 'rsbuild-plugin',
  apply: 'build',
};

Vite 插件

本章节介绍如何将 Vite 插件迁移到 Rsbuild 插件。

现有插件

在迁移一个 Vite 插件之前，建议先检查 Rsbuild 生态中是否存在对应的插件，你可以通过以下页面来查找：

定义一个插件

Rsbuild 插件的定义方式与 Vite 相似，通常都是一个接收插件选项作为参数的函数，并返回插件的描述对象。

Vite 插件：

vitePlugin.ts

const vitePlugin = (options) => ({
  name: 'vite-plugin',
  transform() {
    // ...
  },
});

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = (options) => ({
  name: 'rsbuild-plugin',
  setup(api) {
    api.transform(() => {
      // ...
    });
  },
});

插件 hooks

Rsbuild 的插件 API 覆盖了大部分的 Vite 和 Rollup 插件 hooks，例如：

Vite 插件 hooks	Rsbuild 插件 API
`resolveId`	resolve
`transform`	transform
`config`	modifyRsbuildConfig
`configResolved`	getNormalizedConfig
`configEnvironment`	modifyEnvironmentConfig
`configureServer`	onBeforeStartDevServer
`buildStart`	onBeforeBuild, onBeforeStartDevServer
`buildEnd`	onAfterBuild, onCloseDevServer
`closeBundle`	onCloseBuild, onCloseDevServer
`transformIndexHtml`	modifyHTML, modifyHTMLTags

请参考插件系统文档来了解更多。

`config` 钩子

Rsbuild 提供了 modifyRsbuildConfig 钩子来修改 Rsbuild 配置。由于 Rsbuild 与 Vite 的配置结构存在差异，在迁移 Vite 插件时，需要对配置进行调整。

例如，需要将 Vite 的 define 选项替换为 Rsbuild 的 source.define 选项。

Vite 插件：

vitePlugin.ts

const vitePlugin = {
  name: 'my-plugin',
  config: (config) => {
    config.define = {
      ...config.define,
      FOO: '"foo"',
    };
  },
};

Rsbuild 插件：

rsbuildPlugin.ts

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

TIP

查看配置迁移了解如何将 Vite 的配置迁移到 Rsbuild。

`configEnvironment` 钩子

Rsbuild 提供了 modifyEnvironmentConfig 钩子来修改特定 environment 的配置。

Vite 插件：

const vitePlugin = {
  name: 'config-environment',
  configEnvironment(name, config) {
    if (name === 'web') {
      config.resolve.alias = {
        // ...
      };
    }
  },
};

Rsbuild 插件：

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

`configResolved` 钩子

Rsbuild 提供了 api.getNormalizedConfig 方法来获取已解析的配置。这个方法与 Vite 的 configResolved 钩子的使用场景类似。

Vite 插件：

vitePlugin.ts

const vitePlugin = () => {
  let config;
  return {
    name: 'read-config',
    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },
    transform() {
      console.log(config);
      // ...
    },
  };
};

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = () => ({
  name: 'read-config',
  setup(api) {
    api.transform(() => {
      const config = api.getNormalizedConfig();
      console.log(config);
      // ...
    });
  },
});

`transformIndexHtml` 钩子

Vite 的 transformIndexHtml 钩子对应了 Rsbuild 的两个钩子：

modifyHTML：用于修改 HTML 内容
modifyHTMLTags：用于修改 HTML 标签

下面一个是替换 HTML 标题的示例。

Vite 插件：

vitePlugin.ts

const htmlPlugin = () => {
  return {
    name: 'html-plugin',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    },
  };
};

Rsbuild 插件：

rsbuildPlugin.ts

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

`configureServer` 钩子

Rsbuild 提供了 onBeforeStartDevServer 钩子来替代 Vite 的 configureServer 钩子，它允许你获取 dev server 实例和添加自定义的中间件。

Vite 插件：

vitePlugin.ts

const vitePlugin = () => ({
  name: 'setup-middleware',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      // custom handle request...
    });
  },
});

Rsbuild 插件：

rsbuildPlugin.ts

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

`apply` 属性

Rsbuild 插件提供了与 Vite 插件一致的 apply 属性。

Vite 插件：

vitePlugin.ts

const vitePlugin = {
  name: 'vite-plugin',
  apply: 'build',
};

Rsbuild 插件：

rsbuildPlugin.ts

const rsbuildPlugin = {
  name: 'rsbuild-plugin',
  apply: 'build',
};

#Vite 插件

#现有插件

#定义一个插件

#插件 hooks

#config 钩子

#configEnvironment 钩子

#configResolved 钩子

#transformIndexHtml 钩子

#configureServer 钩子

#apply 属性

#Vite 插件

#现有插件

#定义一个插件

#插件 hooks

#config 钩子

#configEnvironment 钩子

#configResolved 钩子

#transformIndexHtml 钩子

#configureServer 钩子

#apply 属性

Vite 插件

现有插件

定义一个插件

插件 hooks

`config` 钩子

`configEnvironment` 钩子

`configResolved` 钩子

`transformIndexHtml` 钩子

`configureServer` 钩子

`apply` 属性

Vite 插件

现有插件

定义一个插件

插件 hooks

`config` 钩子

`configEnvironment` 钩子

`configResolved` 钩子

`transformIndexHtml` 钩子

`configureServer` 钩子

`apply` 属性