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.