didi/mpx: a Vue-like cross-platform mini program framework that also compiles to React Native

The problem Mpx solves: one Vue-like source tree for many mini program runtimes

China's mini program platforms do not share a runtime. WeChat, Alipay, Baidu, ByteDance, QQ and JD each ship their own component set, their own template directives and their own build expectations. A team that wants to be present on three of them either maintains three codebases or writes one and accepts a translation layer.

Mpx is that translation layer. The README describes it as an enhanced cross-platform framework that supports mini programs, Web and React Native (iOS, Android, Harmony) output. The development model is deliberately close to Vue: single-file components, data reactivity with assignment, watch and computed, a composition API, mixins, a Vuex-style store and a TypeScript layer built on ThisType for type inference. The pitch is that a developer who knows Vue can start writing pages without learning a new mental model.

That matters most for product teams inside larger organisations, which is where Mpx comes from. The README calls out cross-team development through packages and subpackages, which is the shape of the problem when several squads contribute to one mini program and each needs its own build output. The framework also lists i18n, unit testing, E2E testing, utility-first CSS and SSR as supported capabilities, which is a broader surface than most mini program toolchains attempt.

How the compile and runtime split works

Mpx is not a runtime-only abstraction. The README's platform table makes the division explicit: for mini programs the framework is responsible for both the compiled output and the runtime, and the same is true for Web, while for React Native it emits RN JS and resource artefacts.

The compile target is selected with a mode value. The README lists wx, ali, swan, qq, tt and jd for mini programs, web for the browser, and ios, android and harmony for React Native. Templates can branch on the injected __mpx_mode__ variable, and a branch that evaluates to false is not emitted into dist. That is a compile-time decision, not a runtime check, so platform-specific markup costs nothing on the platforms that do not use it.

File-level conditional compilation works alongside the template branches. On the RN targets there is an extra rule worth knowing: when an android or harmony build finds no matching platform file, it falls back to the .ios file. The README's advice is to write one shared RN implementation such as index.ios.mpx and add .android.mpx or .harmony.mpx only where the platforms actually differ. That fallback is convenient, and it is also a trap for anyone who assumes a missing .android.mpx file means the platform has no implementation.

The build layer is webpack 5, with persistent caching and compatibility with the webpack ecosystem. The README states the framework runtime is 14KB, and points to subpackage handling as part of the size story. The repository is a Lerna monorepo, with the framework split into packages/ and a separate docs-vitepress/ documentation site, so the published artefacts are individual npm packages rather than one bundle.

Installing Mpx and running the first page

The README's quick start goes through the official CLI. Install the scaffolder globally, then create a project, install its dependencies and start the development server.

npm i -g @mpxjs/cli
mpx create mpx-project
cd mpx-project
npm i
npm run serve

For a production build the README gives npm run build. The development and production outputs land in dist, and the README says to open the platform folder inside dist with the corresponding mini program developer tool to preview the result. So the loop is: run serve, open dist/<platform> in the vendor IDE, and edit source files while the watcher rebuilds.

The page itself is a single-file component. The README's example registers a page with createPage from @mpxjs/core and uses wx: prefixes for template binding, including wx:for, wx:class, wx:model, wx:ref, wx:show and a dynamic component tag whose is attribute takes a component name registered in the page json.

<template>
  <view class="container" wx:style="{{dynamicStyle}}">
    <view class="title">{{reversedTitle}}</view>
    <view wx:for="{{list}}" wx:key="id" wx:class="{{ {active:item.active} }}" bindtap="handleTap(index)">
      <input type="text" wx:model="{{list[index].content}}"/>
    </view>
  </view>
</template>

Two details are worth copying from that example. Event handlers receive arguments directly, so handleTap(index) gives the handler the current index without a dataset round trip. And computed properties are declared next to data, which is why reversedTitle can be bound in the template as if it were a plain field. For React Native, the README says to choose an RN-capable template at creation time and then use the generated scripts.

npm run serve:ios
npm run serve:android
npm run serve:harmony

The README notes that the exact script names come from the scaffold, and that RN output normally lands in dist/react-native/ or in a directory agreed with the RN container project. It does not give a full RN project setup walkthrough in the README itself; the linked RN quick start guide is where that lives.

Where Mpx stops: Harmony packaging, native containers and the RN fallback

The most important limitation is stated plainly in the README and is easy to misread from the feature list. Harmony support is part of the React Native output chain, not a separate mini program target. When harmony is the compile mode, Mpx produces JS and resource artefacts that a Harmony-side React Native or RNOH project consumes. Native project creation, packaging, signing and release stay with the Harmony RN container and its toolchain.

That means a team that wants a Harmony app still owns a native build pipeline. Mpx removes the business-logic duplication, not the platform engineering. Anyone reading "supports Harmony" as "one command produces a shippable Harmony app" will be disappointed.

The same boundary applies to the other targets. Mpx compiles and provides a runtime; the vendor developer tools still do the previewing, and the RN container still does the native work. The README does not document rollback, migration away from Mpx, or what happens to a project that needs to drop the framework later, so that risk has to be assessed from the code rather than the documentation.

There is also a version and maintenance question. The last push to the repository was on 2026-09-23, and the most recent release listed is v2.11.1 on 2026-07-22, with v2.11.0 on 2026-07-13 and v2.10.21 on 2026-06-05. The project is not archived. The README references a 2.9 release with atomic CSS, SSR and build size work, plus a migration guide for that version, which tells you the framework has gone through breaking-version migrations before and documented them.

Mpx versus Taro and uni-app

The obvious comparison is Taro, which also compiles one source tree to multiple mini program platforms, and uni-app, which does the same with a Vue-flavoured syntax and its own IDE story. The difference in approach is where the framework sits relative to the platform.

Mpx leans on the mini program template syntax itself, with wx: prefixed directives in the README example, and layers reactivity, computed values and a component model on top. Its compile output is intended to stay compatible with native mini program code, and the README lists progressive adoption and native component support as features. That makes partial migration plausible: an existing mini program can take on Mpx page by page rather than being rewritten. Taro, by contrast, is built around React and JSX, so a team with a React background will find its component model more familiar, while a team with a Vue background will find Mpx closer to what they already write.

uni-app occupies a similar Vue-adjacent position but is oriented around its own tooling and a plugin market. Mpx's differentiator in the README is the React Native output covering iOS, Android and Harmony, plus the webpack 5 build layer with persistent caching and npm subpackage handling. If your target list is mini programs only, that RN path adds build surface you will never use, and a simpler compiler may be easier to reason about. If you need a native app from the same source, the RN output is the reason to look at Mpx at all.

Licence and the cost of staying current

Mpx is Apache-2.0, which permits commercial and closed-source use and includes an explicit patent grant. The framework is published as npm packages under the @mpxjs scope, with @mpxjs/cli as the scaffolder and @mpxjs/core providing createPage and the rest of the runtime API. Nothing in the README imposes additional terms on the compiled output, so the licence burden falls on the packages you depend on, not on the mini program you ship. That is a general reading of Apache-2.0 and not legal advice; your own counsel should confirm it for your distribution model.

The upgrade cost is the part teams underestimate. The repository is a Lerna monorepo, and the root package.json wires releases through lerna version followed by lerna publish from-package, so the individual @mpxjs packages can move independently. The README points to a dedicated migration guide for the 2.9 line, which is the pattern to expect: minor releases that are routine, with occasional versions that require reading a migration document before you bump. Pin your @mpxjs versions and read the migration guide for any release that has one. Because the framework owns both the compiler and the runtime, a version skew between the two is a class of bug that a compiler-only tool does not have.

Editorial conclusion

Adopt Mpx if you already ship mini programs on several platforms and want one Vue-like codebase plus a Web and React Native target. Do not adopt it if you need a plain mini program with no build layer, or if you expect the framework to handle Harmony native packaging, which the README assigns to the Harmony RN container and toolchain. Before committing, verify that the scaffold template you pick actually emits the RN scripts the README lists, and read the RN platform fallback rules for .ios.mpx files.

Frequently asked questions

Official sources

1. didi/mpx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases