weapp-vite

6.15.17 verified Mon Apr 27 auth: no javascript

A modern build toolchain for WeChat Mini Programs based on Vite (v6.x). Supports TypeScript, SCSS/LESS, Vue 3 SFC with full template syntax (v-if, v-for, v-model), scoped CSS, dynamic components, KeepAlive, and HMR. Current stable version 6.15.17, released as patches weekly. Key differentiators: first-class Vue 3 integration in mini-program environment, Vite plugin ecosystem compatibility, built-in screenshot/comparison CLI, and AI-agent-friendly local docs. Requires Node >=20.19.0 or >=22.12.0.

Common errors

error Error: Cannot find module 'weapp-vite/config' ↓

cause Importing defineConfig from the wrong path or missing dependency.

fix

Run 'npm install weapp-vite --save-dev' and use 'import { defineConfig } from 'weapp-vite/config''.

error TypeError: weappVite is not a function ↓

cause Using CommonJS require with the ESM-only package.

fix

Use ESM import: 'import { defineConfig } from 'weapp-vite/config''. Do not use require().

error The engine 'node' is incompatible with this module. Expected version '^20.19.0 || >=22.12.0' ↓

cause Node.js version is older than required (e.g., Node 18 or Node 20.0–20.18).

fix

Upgrade to Node.js 20.19.0+ or 22.12.0+ (e.g., using nvm: nvm install 22.12.0).

Warnings

breaking Node.js >=20.19.0 or >=22.12.0 required (engine constraint). Earlier versions (including Node 18 and Node 20.0–20.18) will fail to install or run. ↓

fix Upgrade Node.js to ^20.19.0 or ^22.12.0; use nvm or fnm to manage versions.

gotcha The 'wv' CLI alias is only available if weapp-vite is installed locally in the project. Global install may not register the alias properly. ↓

fix Ensure weapp-vite is listed as a devDependency and run via npx (npx wv build) or a package.json script.

deprecated Prior to v6.15.15, inject() with no default value and missing provider would throw; now returns undefined with a warning. ↓

fix Update to >=6.15.15 and review code that relied on the throw behavior; add default values where needed.

gotcha HMR snapshot rebuild may be triggered for layout or route changes; the build logs include a 'reason' summary. Ignoring these logs may mislead developers to think rebuilds are unnecessary. ↓

fix Check the pending reason in build logs; use '--hmr-profile' to analyze slow points.

Install

npm install weapp-vite

yarn add weapp-vite

pnpm add weapp-vite

Imports

defineConfig

wrong

import { defineConfig } from 'weapp-vite'

correct

import { defineConfig } from 'weapp-vite/config'

defineConfig is exported from the /config subpath, not the main entry.

weapp-vite (CLI)
wrong
```
npx weapp-vite vite build
```
correct
```
npx weapp-vite build
```
CLI is invoked directly as 'weapp-vite' or 'wv'; do not manually run 'vite' commands.
default (create-weapp-vite)
wrong
```
npm init weapp-vite
```
correct
```
npm create weapp-vite@latest
```
Scaffold tool is a separate package 'create-weapp-vite'; do not use 'npm init' with the weapp-vite package.

Quickstart

Showcases a minimal weapp-vite config enabling Vue support and a Vue SFC component with template, script setup, and scoped styles.

// vite.config.ts or weapp-vite.config.ts
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    srcRoot: 'src',
    vue: {
      enable: true,
      template: {
        removeComments: true,
        htmlTagToWxml: true,
        htmlTagToWxmlTagClass: true,
      },
    },
  },
})

// App.vue
<script setup lang="ts">
import { ref } from 'vue'

const message = ref('Hello Vue in Mini-program!')

function handleClick() {
  console.log('Button clicked!')
}
</script>

<template>
  <view class="container">
    <text>{{ message }}</text>
    <button @click="handleClick">Click</button>
  </view>
</template>

<style scoped>
.container {
  padding: 20rpx;
}
</style>