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 remove vite

• Install Rsbuild dependencies:

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.

{
  "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:

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:

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

Then add the following config.

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:

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

Configuration migration#

Here is the corresponding Rsbuild configuration for Vite configuration:

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.

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:

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:

- /// <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:

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.