#Vite

This guide explains how to migrate a Vite project to Rsbuild.

#Installing dependencies

First, replace Vite's npm dependencies with Rsbuild's equivalents.

• Remove Vite dependencies:

npm remove vite

yarn remove vite

pnpm remove vite

bun remove vite

deno remove npm:vite

• Install Rsbuild dependencies:

npm add @rsbuild/core -D

yarn add @rsbuild/core -D

pnpm add @rsbuild/core -D

bun add @rsbuild/core -D

deno add npm:@rsbuild/core -D

#Test tooling

Vitest uses Vite to transform and run tests, so retain Vite and any Vite plugins referenced by vitest.config.* while you use Vitest. To remove Vite from the test toolchain, you can migrate to Rstest, which reuses your Rsbuild configuration through @rstest/adapter-rsbuild. See the Testing guide and the Rstest migration guide for the required configuration and test API changes.

Remove Vite only after confirming that no other development tool or dependency still requires it.

#TanStack Start

TanStack Start manages client and server entries, deployment output, and framework-specific plugins. Follow the dedicated TanStack Start migration guide instead of the generic build entry steps below.

#Updating npm scripts

Next, update the npm scripts in your package.json to run Rsbuild CLI commands.

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "dev": "rsbuild",
    "build": "rsbuild build",
    "preview": "rsbuild preview"
  }
}

#Create configuration file

Create an Rsbuild configuration file named rsbuild.config.ts alongside 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 auto-detects a src/index.* module such as src/index.ts or src/index.js.

When migrating from Vite to Rsbuild, 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 configuration:

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

Rsbuild automatically injects the <script> tags into the generated HTML files during the build.

#Migrating plugins

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

Refer to Plugin list to learn more about available plugins.

#Config migration

Here is the corresponding Rsbuild configuration for each Vite option:

Notes:

• The table above doesn't cover every Vite option; feel free to add more.

#Server port

Vite's dev server uses port 5173 by default, while Rsbuild uses port 3000 by default. If your project depends on 5173, you can keep Vite's original port with the following configuration:

export default {
  server: {
    port: 5173,
  },
};

#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). Rename client variables in .env files, deployment configuration, and application code:

- VITE_API_URL
+ PUBLIC_API_URL

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
• import.meta.env.SSR

#Preset types

Vite provides some preset type definitions through vite/client. When migrating to Rsbuild, replace it with the preset types provided by @rsbuild/core:

{
  "compilerOptions": {
    "types": ["vite/client"],
    "types": ["@rsbuild/core/types"] 
  }
}

#Web Workers

When migrating worker query imports from Vite, Rsbuild supports ?worker and ?worker&inline:

import Worker from './worker.ts?worker';
import InlineWorker from './worker.ts?worker&inline';

Rsbuild does not support Vite's ?worker&url query suffix. If you use it to create a dedicated worker, migrate to the standard new Worker() constructor syntax instead:

const worker = new Worker(new URL('./worker.ts', import.meta.url), {
  type: 'module',
});

Rsbuild also does not support Vite's ?sharedworker, ?sharedworker&inline, or ?sharedworker&url query suffixes. To preserve shared worker behavior, use the standard new SharedWorker() constructor syntax instead:

const sharedWorker = new SharedWorker(new URL('./worker.ts', import.meta.url), {
  type: 'module',
});

The constructor syntax also lets you pass standard WorkerOptions or SharedWorkerOptions, such as name, type, and credentials. See Web Workers for more details.

#Glob import

Rsbuild >= 2.0.8 is compatible with import.meta.glob(), so you can keep the Vite code unchanged when migrating to Rsbuild.

#vite-tsconfig-paths

Rsbuild supports TypeScript's paths option as alias out of the box, so you can remove the vite-tsconfig-paths dependency directly.

See Path aliases for more details.

#Migrating Vite plugins

See Vite plugin to learn how to migrate Vite plugins.

#Validating results

After completing the steps above, the basic migration from Vite to Rsbuild is complete. You can now run the npm run dev command to try starting the dev server.

If you encounter issues during the build process, debug using the error log, or check the Vite configuration for any settings that haven't been migrated to Rsbuild.

#Contents supplement

This document covers only part of the migration process. If you have content to add, feel free to contribute via a pull request 🤝.

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