Vue CLI

This chapter introduces how to migrate a Vue CLI project to Rsbuild.

Install Dependencies

First, you need to replace the npm dependencies of Vue CLI with Rsbuild's dependencies.

  • Remove Vue CLI dependencies:
npm
yarn
pnpm
bun
npm remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint core-js
  • Install Rsbuild dependencies:
npm
yarn
pnpm
bun
npm add @rsbuild/core @rsbuild/plugin-vue -D
TIP

If your project is based on Vue 2, replace @rsbuild/plugin-vue with @rsbuild/plugin-vue2.

Update npm scripts

Next, you need to update the npm scripts in the package.json file to Rsbuild's CLI commands.

{
  "scripts": {
    "serve": "rsbuild dev",
    "build": "rsbuild build",
    "preview": "rsbuild preview"
  }
}
TIP

Rsbuild does not integrate ESLint, so it does not provide a command to replace vue-cli-service lint. You can directly use ESLint's CLI commands as an alternative.

Create Configuration File

Create a Rsbuild configuration file rsbuild.config.ts in the same directory as package.json, and add the following content:

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

export default defineConfig({
  plugins: [pluginVue()],
  source: {
    // Specify the entry file
    entry: {
      index: './src/main.js',
    },
  },
});
TIP

If your project is based on Vue 2, use import { pluginVue2 } from '@rsbuild/plugin-vue2';.

HTML Template

Vue CLI uses the public/index.html file as the default HTML template. In Rsbuild, you can specify the HTML template through html.template:

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

In the HTML template, if you are using the BASE_URL variable from Vue CLI, replace it with Rsbuild's assetPrefix variable and use a forward slash for concatenation:

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

This completes the basic migration from Vue CLI to Rsbuild. You can now run the npm run serve command to try starting the dev server.

Configuration Migration

Here is the corresponding Rsbuild configuration for Vue CLI configuration:

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

Notes:

  • When migrating configureWebpack, note that most of the Webpack and Rsbuild configs are the same, but there are also some differences or functionalities not implemented in Rsbuild.
  • The above table does not cover all configurations of Vue CLI, feel free to add more.

Environment Variables

Vue CLI injects environment variables starting with VUE_APP_ into the client code by default, while Rsbuild injects environment variables starting with PUBLIC_ by default (see public variables).

To be compatible with Vue CLI's behavior, you can manually call Rsbuild's loadEnv method to read environment variables starting with VUE_APP_, and inject them into the client code through the source.define config.

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

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

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

Contents Supplement

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via pull request 🤝.

The documentation for rsbuild can be found in the rsbuild/packages/document directory.