Vite

Vite is an excellent and powerful build tool. In some cases, you might need to migrate a Vite application to Rsbuild. You can refer to this guide to perform the migration.

Installing Dependencies

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

  • Remove Vite dependencies:
npm
yarn
pnpm
bun
npm remove vite
  • Install Rsbuild dependencies:
npm
yarn
pnpm
bun
npm add @rsbuild/core -D

Updating npm scripts

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

package.json
{
  "scripts": {
-   "dev": "vite",
-   "build": "vite build",
-   "preview": "vite preview"
+   "dev": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}

Create Configuration File

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

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

export default defineConfig({
  plugins: [],
});

Build Entry

The default build entry points for Rsbuild and Vite are different. Vite uses index.html as the default entry, while Rsbuild uses src/index.js.

When migrating from Vite to Rsbuild, you can use Rsbuild's source.entry to set the build entry and html.template to set the template.

Using a newly created Vite project as an example, first delete the <script> tags from index.html:

index.html
- <script type="module" src="/src/main.ts"></script>

Then add the following config.

rsbuild.config.ts
export default {
  html: {
    template: './index.html',
  },
  source: {
    entry: {
      index: './src/main.ts',
    },
  },
};

Rsbuild will automatically inject the <script> tags into the generated HTML files during the build process.

Migrating Plugins

Most common Vite plugins can be easily migrated to Rsbuild plugins, such as:

Vite Rsbuild
@vitejs/plugin-react @rsbuild/plugin-react
@vitejs/plugin-react-swc @rsbuild/plugin-react
@vitejs/plugin-vue @rsbuild/plugin-vue
@vitejs/plugin-vue2 @rsbuild/plugin-vue2
@vitejs/plugin-vue-jsx @rsbuild/plugin-vue-jsx
@vitejs/plugin-vue2-jsx @rsbuild/plugin-vue2-jsx
@vitejs/plugin-basic-ssl @rsbuild/plugin-basic-ssl
@vitejs/plugin-legacy No need to use, see Browser Compatibility for details
@sveltejs/vite-plugin-svelte @rsbuild/plugin-svelte
vite-plugin-svgr @rsbuild/plugin-svgr
vite-plugin-checker @rsbuild/plugin-type-check
vite-plugin-eslint @rsbuild/plugin-eslint
vite-plugin-static-copy output.copy
vite-plugin-node-polyfills @rsbuild/plugin-node-polyfill
vite-plugin-solid @rsbuild/plugin-solid

You can refer to Plugin List to learn more about available plugins.

Configuration Migration

Here is the corresponding Rsbuild configuration for Vite configuration:

Vite Rsbuild
root root
mode mode
base server.base
define source.define
plugins plugins
envDir Env Directory
publicDir server.publicDir
resolve.alias source.alias
resolve.conditions tools.rspack.resolve.conditionNames
resolve.mainFields tools.rspack.resolve.mainFields
resolve.extensions tools.rspack.resolve.extensions
resolve.preserveSymlinks tools.rspack.resolve.symlinks
html.cspNonce security.nonce
css.modules output.cssModules
css.postcss tools.postcss
css.preprocessorOptions.sass pluginSass
css.preprocessorOptions.less pluginLess
css.preprocessorOptions.stylus pluginStylus
css.devSourcemap output.sourceMap
css.lightningcss tools.lightningcssLoader
server.host, preview.host server.host
server.port, preview.port server.port
server.strictPort, preview.strictPort server.strictPort
server.https, preview.https server.https
server.open, preview.open server.open
server.proxy, preview.cors server.proxy
server.headers, preview.headers server.headers
server.hmr dev.hmr, dev.client
build.target, build.cssTarget Browserslist
build.outDir, build.assetsDir output.distPath
build.assetsInlineLimit output.dataUriLimit
build.cssMinify output.minify
build.sourcemap output.sourceMap
build.lib Use Rslib
build.manifest output.manifest
build.ssrEmitAssets output.emitAssets
build.minify, build.terserOptions output.minify
build.emptyOutDir output.cleanDistPath
build.copyPublicDir server.publicDir
build.reportCompressedSize performance.printFileSize
ssr, worker environments

Notes:

  • The above table does not cover all configurations of Vue CLI, feel free to add more.

Environment Variables

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

To be compatible with Vite's behavior, you can manually call Rsbuild's loadEnv method to read environment variables starting with VITE_, 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: ['VITE_'] });

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

Rsbuild injects the following environment variables by default:

  • import.meta.env.MODE
  • import.meta.env.BASE_URL
  • import.meta.env.PROD
  • import.meta.env.DEV

For import.meta.env.SSR, you can set it through the environments and source.define configuration options:

rsbuild.config.ts
export default defineConfig({
  environments: {
    web: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(false),
        },
      },
    },
    node: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(true),
        },
      },
      output: {
        target: 'node',
      },
    },
  },
});

Preset Types

Vite provides some preset type definitions through the vite-env.d.ts file. When migrating to Rsbuild, you can use the preset types provided by @rsbuild/core:

src/env.d.ts
- /// <reference types="vite/client" />
+ /// <reference types="@rsbuild/core/types" />

Glob Import

Vite provides import.meta.glob() for importing multiple modules.

When migrating to Rsbuild, you can use the import.meta.webpackContext() function of Rspack instead:

  • Vite:
const modules = import.meta.glob('./dir/*.js');

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod);
  });
}
  • Rsbuild:
const context = import.meta.webpackContext('./dir', {
  // Whether to search subdirectories
  recursive: false,
  regExp: /\.js$/,
});

for (const path of context.keys()) {
  const mod = context(path);
  console.log(path, mod);
}

Validating Results

After completing the above steps, you have completed the basic migration from Vite to Rsbuild. You can now run the npm run serve command to try starting the dev server.

If you encounter any issues during the build process, please debug according to the error log, or check the Vite configuration to see if there are any necessary configurations that have not been migrated to Rsbuild.

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/website directory.