Mini Program Framework Migration Practice

Mini Program Framework Migration Practice

The article provides an overview of WeChat mini programs and the underlying principles of the mpvue and uni-app frameworks, then describes a real‑world migration of a large mpvue project to uni-app .

Project Background

The "拼房帝" mini program, built on mpvue , has grown to over 190 native pages, leading to performance bottlenecks and maintenance difficulties. The team evaluated migration to uni-app , which shares Vue syntax but offers better performance and active maintenance.

WeChat Mini Program Architecture

WeChat mini programs use a dual‑thread architecture: the rendering layer (WXML, WXSS) runs in a WebView , while the logic layer runs JavaScript in a separate engine. Data updates are driven by setData , and communication between layers occurs via the native bridge.

Framework Basics

Mini‑program frameworks (WePy, mpvue, uni‑app, Taro) compile Vue‑like syntax into mini‑program code. They perform a compilation phase (converting DSL to WXML/WXSS/JS/JSON) and a runtime phase (handling data, events, and lifecycle).

mpvue Internals

mpvue forks Vue 2.4.1, adds a mini‑program runtime, and modifies the compiler. During compilation, mpvue-loader transforms Vue SFCs into WXML/WXSS. At runtime, a Vue instance and a mini‑program page instance are created; updates are sent to the view via setData . Lifecycle hooks are synchronized by calling callHook on the Vue instance.

function callHook(vm, hook, params) { /* source code omitted for brevity */ }

Event handling uses a proxy method ( handleProxy ) that maps view events to Vue methods. Data updates are sent wholesale with setData , which can be inefficient; later mpvue versions added diffing and throttling.

uni‑app Analysis

uni‑app, also based on Vue, supports multiple platforms (iOS, Android, H5, various mini‑programs). It improves performance by using custom components, eliminating vnode diffing, and applying fine‑grained diff calculations before calling setData . It also benefits from active maintenance and a richer ecosystem.

Comparison Table

Dimension

mpvue

uni‑app

Supports custom components

No

Yes

setData update granularity

Full‑page updates

Diff‑based, path‑level updates

Sub‑component lifecycle support

Yes

No

Vue syntax coverage

Basic

Extended (filters, complex expressions)

Maintenance status

Unmaintained

Officially maintained

Community ecosystem

Weak

Rich

Cross‑platform capability

Mini‑program only

Mini‑program, H5, iOS, Android

Migration Plan

Initialize a new uni‑app project.

Copy the original mpvue src files into the uni‑app project.

Convert app.json / main.js page configurations to pages.json .

Rename page entry files to main.vue and remove the old main.js / main.json .

Copy static assets and adjust resource paths.

Migrate custom webpack configuration to vue.config.js as per uni‑app docs.

Install dependencies and run the project.

To automate these steps, the team created an npm CLI tool mpvue-to-uniapp that performs most of the conversion automatically.

Handling Lifecycle Mismatch

Since uni‑app components do not support mini‑program page lifecycle hooks, a global mixin is introduced that, on component mounted , registers the component’s lifecycle methods (e.g., onLoad , onShow ) onto the root page component, and removes them on beforeDestroy . This restores the behavior of mpvue in uni‑app.

Vue.mixin({
  mounted() { /* register hooks */ },
  beforeDestroy() { /* unregister hooks */ },
  onLoad(){}, onShow(){}, /* … */
});

Additional Migration Considerations

Adjust API calls that require explicit this binding (e.g., wx.createSelectorQuery ).

Ensure prop definitions and usage follow uni‑app’s stricter rules.

Replace mpvue‑specific namespaces with uni‑app equivalents.

Update event parameter handling to match uni‑app’s event object shape.

Conclusion

The migration was completed in two weeks, resulting in significant performance gains, lower memory usage, and faster development cycles. The team recommends uni‑app for new mini‑program projects due to its superior performance, active maintenance, and broader cross‑platform support.