create-weapp-vite

2.3.10 verified Mon Apr 27 auth: no javascript

Official scaffolding tool for weapp-vite, a Vite-based build tool for WeChat Mini Programs. Current stable version 2.3.10. Actively maintained with weekly releases. Key differentiator: provides multiple templates (Wevu, TDesign, Tailwindcss, Vant) and a programmable API for CI/CD, automatically aligning weapp-vite and wevu versions. Requires Node.js ^20.19.0 || >=22.12.0.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/create-weapp-vite/index.mjs not supported. ↓

cause Using require() on an ESM-only package with Node.js < 20.19.0 or in a CJS project.

fix

Upgrade Node.js to >=20.19.0 and change to ESM ("type": "module" in package.json) or use await import('create-weapp-vite').

error Template 'my-custom-template' not found. Available templates: default, wevu, wevu-tdesign, tailwindcss, tdesign, vant, plugin, lib ↓

cause Specifying a template name that does not exist or is misspelled.

fix

Use one of the supported template names: default, wevu, wevu-tdesign, tailwindcss, tdesign, vant, plugin, lib.

error The "path" argument must be of type string. Received undefined ↓

cause Calling createProject() without a project name or with an undefined argument.

fix

Pass a non-empty string as the first argument to createProject(), e.g., createProject('my-app', TemplateName.default).

error Cannot find package 'create-weapp-vite' ↓

cause The package is not installed. When using pnpm create, it fetches the package on the fly, but if you try to import it directly without installing, it fails.

fix

Run pnpm add create-weapp-vite or npm install create-weapp-vite before importing.

Warnings

breaking Requires Node.js version ^20.19.0 or >=22.12.0. Older Node.js versions will fail at runtime. ↓

fix Update Node.js to 20.19.0+ or 22.12.0+ using nvm or your package manager.

gotcha The package is ESM-only since v2. Using CommonJS require() throws a runtime error. ↓

fix Ensure your project uses ESM ("type": "module" in package.json) or use dynamic import() if needed.

deprecated The default export createProject was removed in v2. Use named export createProject instead. ↓

fix Change `import createProject from 'create-weapp-vite'` to `import { createProject } from 'create-weapp-vite'`.

gotcha Template names are case-sensitive. Using incorrect casing (e.g., 'Wevu' vs 'wevu') will throw an error. ↓

fix Use the TemplateName enum or exact lowercase string: 'default', 'wevu', 'wevu-tdesign', 'tailwindcss', 'tdesign', 'vant', 'plugin', 'lib'.

gotcha When using the CLI non-interactively, the project name must be provided as the first positional argument; omitting it will default to interactive mode. ↓

fix Always supply a project name when using non-interactive mode, e.g., `pnpm create weapp-vite my-app wevu`.

Install

npm install create-weapp-vite

yarn add create-weapp-vite

pnpm add create-weapp-vite

Imports

createProject

wrong

const { createProject } = require('create-weapp-vite')

correct

import { createProject } from 'create-weapp-vite'

ESM-only; CommonJS require will fail.

TemplateName

wrong

import TemplateName from 'create-weapp-vite'

correct

import { TemplateName } from 'create-weapp-vite'

TemplateName is a named export, not default.

default (createProject)

wrong

import createProject from 'create-weapp-vite'

correct

import { createProject } from 'create-weapp-vite'

No default export; use named import.

Quickstart

Creates a new WeChat Mini Program project using the 'wevu' template via the programmatic API.

import { createProject, TemplateName } from 'create-weapp-vite'

async function main() {
  await createProject('my-miniapp', TemplateName.wevu)
  console.log('Project created!')
}

main().catch(console.error)