{"id":22976,"library":"weapp-vite","title":"weapp-vite","description":"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.","status":"active","version":"6.15.17","language":"javascript","source_language":"en","source_url":"https://github.com/weapp-vite/weapp-vite","tags":["javascript","weapp","vite","ts","wxml","wxss","mp","miniprogram","scss","typescript"],"install":[{"cmd":"npm install weapp-vite","lang":"bash","label":"npm"},{"cmd":"yarn add weapp-vite","lang":"bash","label":"yarn"},{"cmd":"pnpm add weapp-vite","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: weapp-vite is a Vite-based build tool, requires Vite as the core bundler.","package":"vite","optional":false},{"reason":"optional peer dependency: needed only when using Vue SFC support (weapp.vue.enable: true).","package":"vue","optional":true}],"imports":[{"note":"defineConfig is exported from the /config subpath, not the main entry.","wrong":"import { defineConfig } from 'weapp-vite'","symbol":"defineConfig","correct":"import { defineConfig } from 'weapp-vite/config'"},{"note":"CLI is invoked directly as 'weapp-vite' or 'wv'; do not manually run 'vite' commands.","wrong":"npx weapp-vite vite build","symbol":"weapp-vite (CLI)","correct":"npx weapp-vite build"},{"note":"Scaffold tool is a separate package 'create-weapp-vite'; do not use 'npm init' with the weapp-vite package.","wrong":"npm init weapp-vite","symbol":"default (create-weapp-vite)","correct":"npm create weapp-vite@latest"}],"quickstart":{"code":"// vite.config.ts or weapp-vite.config.ts\nimport { defineConfig } from 'weapp-vite/config'\n\nexport default defineConfig({\n  weapp: {\n    srcRoot: 'src',\n    vue: {\n      enable: true,\n      template: {\n        removeComments: true,\n        htmlTagToWxml: true,\n        htmlTagToWxmlTagClass: true,\n      },\n    },\n  },\n})\n\n// App.vue\n<script setup lang=\"ts\">\nimport { ref } from 'vue'\n\nconst message = ref('Hello Vue in Mini-program!')\n\nfunction handleClick() {\n  console.log('Button clicked!')\n}\n</script>\n\n<template>\n  <view class=\"container\">\n    <text>{{ message }}</text>\n    <button @click=\"handleClick\">Click</button>\n  </view>\n</template>\n\n<style scoped>\n.container {\n  padding: 20rpx;\n}\n</style>","lang":"typescript","description":"Showcases a minimal weapp-vite config enabling Vue support and a Vue SFC component with template, script setup, and scoped styles."},"warnings":[{"fix":"Upgrade Node.js to ^20.19.0 or ^22.12.0; use nvm or fnm to manage versions.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure weapp-vite is listed as a devDependency and run via npx (npx wv build) or a package.json script.","message":"The 'wv' CLI alias is only available if weapp-vite is installed locally in the project. Global install may not register the alias properly.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Update to >=6.15.15 and review code that relied on the throw behavior; add default values where needed.","message":"Prior to v6.15.15, inject() with no default value and missing provider would throw; now returns undefined with a warning.","severity":"deprecated","affected_versions":"<6.15.15"},{"fix":"Check the pending reason in build logs; use '--hmr-profile' to analyze slow points.","message":"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.","severity":"gotcha","affected_versions":">=6.15.15"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install weapp-vite --save-dev' and use 'import { defineConfig } from 'weapp-vite/config''.","cause":"Importing defineConfig from the wrong path or missing dependency.","error":"Error: Cannot find module 'weapp-vite/config'"},{"fix":"Use ESM import: 'import { defineConfig } from 'weapp-vite/config''. Do not use require().","cause":"Using CommonJS require with the ESM-only package.","error":"TypeError: weappVite is not a function"},{"fix":"Upgrade to Node.js 20.19.0+ or 22.12.0+ (e.g., using nvm: nvm install 22.12.0).","cause":"Node.js version is older than required (e.g., Node 18 or Node 20.0–20.18).","error":"The engine 'node' is incompatible with this module. Expected version '^20.19.0 || >=22.12.0'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}