Master WeChat Mini‑Program Development with the Wepy Framework: A Complete Guide

Introduction

Wepy is a development framework that brings traditional H5 development habits to WeChat mini‑programs, allowing developers to use NPM packages, component‑based architecture, and modern JavaScript features such as async/await.

Wepy Demo Projects

Three demo projects are provided: a standard demo generated with wepy new demo, a mobile‑recharge demo, and an open‑source WeChat‑style chat interface. All demos run on both Android and iOS devices.

Demo repository: https://github.com/wepyjs/wepy-wechat-demo

Quick Start

Code Conventions

Use camelCase for variables and methods; avoid names starting with $ unless they are framework‑provided.

File suffix for pages, components, and entry files is .wpy.

Develop with ES6 syntax to leverage language sugar.

All WeChat API calls are wrapped with Promise, enabling async/await usage.

Project Creation

Install Wepy

npm install wepy-cli -g

Create a Demo

wepy new myproject

Real‑time Build

wepy build --watch

Project Structure

The framework generates a dist directory for the mini‑program output. The .wpy file consists of three parts: <style> (maps to wxss), <template> (maps to wxml), and <script> (maps to js).

Main Problems Solved

Development Mode Conversion

Wepy compiles code to a format that runs natively on the mini‑program platform, bridging the gap between traditional MVVM frameworks and the mini‑program environment.

Component‑Based Development

Components isolate data and events, preventing naming collisions and simplifying maintenance.

External NPM Package Support

During compilation, require statements are resolved, dependencies are copied from node_modules, and paths are rewritten to relative paths, enabling seamless NPM integration.

Single‑File Structure

Wepy replaces the multiple file requirement ( app.json, app.js, app.wxss, etc.) with a unified .wpy file, simplifying project organization.

ES6/7 Features via Babel

Developers can customize the .wepyrc file to enable Babel presets, gaining support for promises, async/await, and other modern JavaScript features.

Component Communication

Wepy provides three methods for inter‑component interaction: $broadcast: parent broadcasts to all descendants (breadth‑first). $emit: child emits upward to ancestors. $invoke: direct method call on a specific component.

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

this.$invoke('ComA', 'someMethod', 'someArgs');

Data Binding

WeChat Native Binding

Uses Page.setData to update the view, which may trigger multiple communications if called repeatedly within a single cycle.

Wepy Binding

Wepy wraps setData with a dirty‑checking mechanism, allowing developers to assign values directly (e.g., this.title = 'this is title') and automatically sync to the view at the end of the function cycle. Outside the cycle, $apply must be called manually.

this.title = 'this is title'

Additional Optimizations

Improved wx.request parameter handling.

Optimized event parameter passing.

Enhanced data‑binding API to avoid undefined bugs and support both this.setData(target, value) and this.setData(object) signatures.

Replaced templates and modules with components for clearer structure.