Vite

This chapter introduces how to migrate a Vite project to Rsbuild.

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:

ViteRsbuild
@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-legacyNo 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-copyoutput.copy
vite-plugin-node-polyfills@rsbuild/plugin-node-polyfill
vite-plugin-solid@rsbuild/plugin-solid
@preact/preset-vite@rsbuild/plugin-preact

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

Configuration migration

Here is the corresponding Rsbuild configuration for Vite configuration:

ViteRsbuild
rootroot
modemode
baseserver.base
definesource.define
pluginsplugins
appTypeserver.historyApiFallback
envDirEnv directory
cacheDirbuildCache
publicDirserver.publicDir
assetsIncludesource.assetsInclude
resolve.aliasresolve.alias
resolve.deduperesolve.dedupe
resolve.extensionsresolve.extensions
resolve.conditionstools.rspack.resolve.conditionNames
resolve.mainFieldstools.rspack.resolve.mainFields
resolve.preserveSymlinkstools.rspack.resolve.symlinks
html.cspNoncesecurity.nonce
css.modulesoutput.cssModules
css.postcsstools.postcss
css.preprocessorOptions.sasspluginSass
css.preprocessorOptions.lesspluginLess
css.preprocessorOptions.styluspluginStylus
css.devSourcemapoutput.sourceMap
css.lightningcsstools.lightningcssLoader
server.host, preview.hostserver.host
server.port, preview.portserver.port
server.cors, preview.corsserver.cors
server.strictPort, preview.strictPortserver.strictPort
server.https, preview.httpsserver.https
server.open, preview.openserver.open
server.proxy, preview.proxyserver.proxy
server.headers, preview.headersserver.headers
server.hmrdev.hmr, dev.client
server.middlewareModeserver.middlewareMode
build.target, build.cssTargetBrowserslist
build.outDir, build.assetsDiroutput.distPath
build.assetsInlineLimitoutput.dataUriLimit
build.cssMinifyoutput.minify
build.sourcemapoutput.sourceMap
build.libUse Rslib
build.manifestoutput.manifest
build.ssrEmitAssetsoutput.emitAssets
build.minify, build.terserOptionsoutput.minify
build.emptyOutDiroutput.cleanDistPath
build.copyPublicDirserver.publicDir
build.reportCompressedSizeperformance.printFileSize
ssr, workerenvironments

Notes:

  • The above table does not cover all configurations of Vite, 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);
}

Migrating Vite plugins

Rsbuild's plugin API covers most of the Vite and Rollup plugin hooks, for example:

Vite plugin hooksRsbuild plugin API
resolveIdresolve
transformtransform
configmodifyRsbuildConfig
configResolvedgetNormalizedConfig
configureServeronBeforeStartDevServer
buildStartonBeforeBuild, onBeforeStartDevServer
buildEndonAfterBuild, onCloseDevServer
closeBundleonCloseBuild, onCloseDevServer

See Plugin system for more details.

Validating results

After completing the above steps, you have completed the basic migration from Vite to Rsbuild. You can now run the npm run dev 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.