Why Taro 4.0’s Vite Integration Fails and How to Fix It

Introduction

Taro 4.0 has been in beta for a long time and is expected to ship a stable version in Q2 of this year. The three most interesting upgrades are support for the HarmonyOS platform, a new CompileMode for WeChat mini‑program runtime, and a Vite‑based build chain.

Creating a Taro 4 Template

First, create a demo with the Taro CLI. The Node version must be >= 18. Install the beta CLI globally and initialise a project:

$ yarn global add @tarojs/cli@beta
$ taro init taro4-demo

If you prefer not to pollute the global Taro version, create a dedicated folder:

$ mkdir taro4 && cd ./taro4
$ yarn add @tarojs/cli@beta
$ npx taro init taro4-demo

After selecting the template options, run the development server: $ yarn dev The Vite log appears and a dist folder is generated. However, the IDE shows a white‑screen error for both WeChat and Alipay mini‑programs.

The default template’s Babel target configuration is incorrect, causing dist/vendors.js to fail when parsed by the mini‑program platform. Replacing the Babel target with a proper browserslist or choosing the mobx template resolves the issue.

{
  "browserslist": [
    "last 3 versions",
    "Android >= 4.1",
    "ios >= 8"
  ]
}

After fixing the configuration, yarn dev runs successfully, hot‑module replacement works, and the IDE displays the page correctly.

Product Analysis

The generated dist/app.js looks similar to the output of the traditional Taro webpack build, but it still uses require instead of the expected ES module import statements.

In Vite’s development mode the output should be pure ES modules, yet the bundle still contains CommonJS require calls, indicating that Taro’s Vite integration is not preserving Vite’s native module format.

Source – vite‑runner

The core logic of the Taro 4 Vite integration lives in the @tarojs/vite-runner package (packages/taro-vite-runner). The entry point imports build from Vite and executes it with a generated configuration.

// taro/packages/taro-vite-runner/src/index.mini.ts
import { build } from 'vite';
export default async function (appPath, rawTaroConfig) {
  // ...prepare commonConfig
  console.log(JSON.stringify(commonConfig, false, 2));
  await build(commonConfig);
};

The final Vite configuration is assembled in taro:vite-mini-config, which ultimately enables a lib‑mode Rollup build. This means the code is fully compiled by Rollup and then transformed by a series of custom plugins into mini‑program compatible code.

Consequently, the Vite‑specific features such as on‑demand ES module loading are not available in the current Taro 4 implementation.

Route On‑Demand

The most anticipated feature of Taro 4 + Vite is route‑level code‑splitting, allowing unused routes and their dependencies to be excluded from the initial bundle. In practice this has not been achieved yet; the mini‑program IDE still performs a full build, which is often several times slower than Webpack.

Previous attempts using react-loadable to lazily load pages required extensive code modifications and were abandoned in favour of a simpler approach that intercepts app.config.js to trigger on‑demand compilation.

My Opinion

For now the safest choice is to stick with the traditional Taro webpack workflow. The current Vite integration works in lib mode, which does not bring the speed benefits of native Vite and still relies on Rollup under the hood.

Studying the source code is worthwhile; Taro’s modular architecture makes it easy to add a new build step with only a single additional package.

I hope future Taro releases will fully integrate Vite’s core features, especially route‑level on‑demand compilation, to combine the best of both worlds.