Vue CLI

本章节介绍如何将 Vue CLI 项目迁移到 Rsbuild。

安装依赖

首先你需要把 Vue CLI 的 npm 依赖替换为 Rsbuild 的依赖。

  • 移除 Vue CLI 的依赖:
npm
yarn
pnpm
bun
npm remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint core-js
  • 安装 Rsbuild 的依赖:
npm
yarn
pnpm
bun
npm add @rsbuild/core @rsbuild/plugin-vue -D
TIP

如果你的项目是基于 Vue 2 的,请将 @rsbuild/plugin-vue 替换为 @rsbuild/plugin-vue2

更新 npm scripts

下一步,你需要把 package.json 中的 npm scripts 更新为 Rsbuild 的 CLI 命令。

package.json
{
  "scripts": {
-   "serve": "vue-cli-service serve",
-   "build": "vue-cli-service build",
+   "serve": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}
TIP

Rsbuild 未集成 ESLint,因此没有提供用于替换 vue-cli-service lint 的命令,你可以直接使用 ESLint 的 CLI 命令 作为替代。

创建配置文件

在 package.json 的同级目录下创建 Rsbuild 的配置文件 rsbuild.config.ts,并添加以下内容:

rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  plugins: [pluginVue()],
  source: {
    // 指定入口文件
    entry: {
      index: './src/main.js',
    },
  },
});
TIP

如果你的项目是基于 Vue 2 的,请使用 import { pluginVue2 } from '@rsbuild/plugin-vue2';

HTML 模板

Vue CLI 默认使用 public/index.html 文件作为 HTML 模板。在 Rsbuild 中,你可以通过 html.template 来指定 HTML 模板:

rsbuild.config.ts
export default defineConfig({
  html: {
    template: './public/index.html',
  },
});

在 HTML 模板中,如果使用了 Vue CLI 的 BASE_URL 变量,请替换为 Rsbuild 的 assetPrefix 变量,并使用斜杠进行连接:

-  <link rel="icon" href="<%= BASE_URL %>favicon.ico">
+  <link rel="icon" href="<%= assetPrefix %>/favicon.ico">

这样就完成了从 Vue CLI 到 Rsbuild 的基本迁移,此时你可以执行 npm run serve 命令来尝试启动开发服务器。

配置迁移

以下是 Vue CLI 配置对应的 Rsbuild 配置:

Vue CLI Rsbuild
publicPath dev.assetPrefix / output.assetPrefix
outputDir / assetsDir output.distPath
filenameHashing output.filenameHash
pages source.entry / html.template / html.title
transpileDependencies source.include
productionSourceMap / css.sourceMap output.sourceMap
crossorigin html.crossorigin
configureWebpack tools.rspack
chainWebpack tools.bundlerChain
css.extract output.injectStyles
css.loaderOptions tools.cssLoader / less / sass / postcss
devServer.proxy server.proxy

说明:

  • 在迁移 configureWebpack 时,注意大部分 Webpack 和 Rspack 配置是相同的,但也存在一些差异或 Rspack 未实现的功能。
  • 上述表格尚未覆盖到 Vue CLI 的所有配置,欢迎补充。

环境变量

Vue CLI 默认会将 VUE_APP_ 开头的环境变量注入到 client 代码中,而 Rsbuild 默认会注入 PUBLIC_ 开头的环境变量(参考 public 变量)。

为了兼容 Vue CLI 的行为,你可以手动调用 Rsbuild 提供的 loadEnv 方法来读取 REACT_APP_ 开头的环境变量,并通过 source.define 配置项注入到 client 代码中。

rsbuild.config.ts
import { defineConfig, loadEnv } from '@rsbuild/core';

const { publicVars } = loadEnv({ prefixes: ['VUE_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});

内容补充

当前文档只涵盖了迁移过程的部分事项,如果你发现有合适的内容可以补充,欢迎通过 pull request 来完善文档 🤝。

Rsbuild 的文档位于 rsbuild/packages/document 目录。