Mastering WePY: Complete Guide to Building Mini‑Program Apps

WePY Mini‑Program Framework Documentation

Demo Showcase

Standard demo generated with wepy new demo Mobile recharge demo built with WePY

Open‑source WeChat‑style chat UI demo

All three demos run on Android and iOS devices.

Chat UI demo download: https://github.com/wepyjs/wepy-wechat-demo

Quick Start

Project Creation and Usage

Install the CLI globally, generate a project, and start live compilation:

npm install wepy-cli -g

wepy new myproject

cd myproject

wepy build --watch

Project Directory Structure

Development Instructions

Use WeChat DevTools to create a new project and select the dist folder.

Disable ES6→ES5 conversion in DevTools (Project → Close ES6 to ES5).

Run wepy build --watch locally for real‑time compilation.

IDE Code Highlighting

Sublime Text : Install the Vue syntax highlight package and associate .wpy files with the .vue pattern.

WebStorm : Install the Vue.js plugin, add *.wpy to the registered file types.

Code Conventions

Use camelCase for variables and methods; avoid leading $ unless referring to framework‑provided APIs.

Component, page, and entry files use the .wpy suffix.

Write code using ES6 syntax; the framework supports async/await and other modern features.

Replace native event bindings with optimized syntax, e.g., @tap="click" instead of bindtap="click".

Use @tap="click({{index}})" for event parameters.

Avoid naming custom components with native tags such as input, button, view, repeat.

Main Problems Solved by WePY

1. Development Mode Conversion

WePY wraps the original mini‑program development mode, making it closer to typical MVVM frameworks. It introduces module‑like features, componentization, and NPM package support.

2. Component‑Based Development

Components are isolated, allowing independent business logic and event handling, which improves maintainability for complex pages.

3. External NPM Package Support

During compilation, require statements are resolved to node_modules and copied as relative paths, enabling the use of third‑party libraries.

4. Single‑File Mode

WePY consolidates component code into a single .wpy file containing <style>, <template>, and <script> sections, simplifying project structure.

5. Babel Compilation

By default, WePY uses Babel to compile ES6/7 features such as Promise and async/await. Configuration can be customized via wepy.config.js (or .wepyrc for older versions).

6. Native API Optimization

WePY wraps native APIs with Promise support and fixes issues like concurrent wx.request calls.

Advanced Configuration

wepy.config.js

After running wepy new demo, a configuration file is generated. Key sections include:

wpyExt : File extension for WePY files (default .wpy).

compilers : List of supported compilers (e.g., wepy-compiler-less, wepy-compiler-sass, wepy-compiler-babel, wepy-compiler-pug).

plugins : Plugins for JS and image compression (e.g., wepy-plugin-uglifyjs, wepy-plugin-imagemin).

File Structure of a .wpy File

<style></style>

– corresponds to wxss. <template></template> – corresponds to wxml. <script></script> – corresponds to js.

The entry file app.wpy does not require a template section and is compiled into app.json, app.js, and app.wxss.

Component Definition

Components inherit from wepy.component and share the same options as pages, except they do not need a config section.

Component Communication

WePY provides three communication methods: $broadcast: Parent component broadcasts to all descendants (breadth‑first). $emit: Child component emits an event to its ancestors. $invoke: Direct method call on a specific component using its path.

Example of emitting an event:

$this.$emit('some-event', 1, 2, 3, 4);

Custom Events

Use the @customEvent.user syntax to bind user‑defined component events. Supported suffixes are .default (bubble), .stop (non‑bubble), and .user (custom).

Slots

Components can define <slot> elements for content distribution, enabling flexible composition.

Mixins

WePY supports default and compatible mixins to share data, methods, and lifecycle hooks across components.

Interceptors

Global interceptors can modify API request configurations, handling config, success, fail, and complete callbacks.

Data Binding

WePY wraps setData with a dirty‑checking mechanism, allowing direct assignment like this.title = 'new title'. Outside the normal lifecycle, call $apply to trigger an update.

API Overview

wepy.event

Provides the event communication methods described above.

wepy.component

Base class for defining reusable components.

wepy.page

Base class for page definitions.

wepy.app

Base class for the application entry point.