Mpx: DiDi's Cross-Platform Framework for Mini-Programs
/mpx
Mpx is DiDi's own cross-platform framework for compiling one codebase to WeChat, Alipay, Baidu, and other mini-programs, plus Web and React Native for iOS, Android, and Harmony. Reach for it if you're building for China's mini-program ecosystem and want Vue-like single-file components instead of hand-wiring three native files per screen; skip it if you're not targeting that platform family, since the docs and community run Chinese-first.
What is Mpx?
Mpx is an open-source, cross-platform framework built and maintained by DiDi that compiles a single Vue-like codebase down to WeChat, Alipay, Baidu, ByteDance, QQ, and JD mini-programs, plus a Web build and React Native apps for iOS, Android, and Harmony. Instead of porting a web framework into the mini-program runtime, it extends each platform's own native template syntax with web-style ergonomics, per the README's stated design.
Core Features and Capabilities
- โReactive data through direct property assignment, plus watch and computed properties.
- โComposition API support alongside the standard options-style API.
- โEnhanced template syntax: dynamic components, style/class binding, inline event handler functions, two-way binding, and refs.
- โA small runtime โ the README states it's 14KB after compression and gzip โ paired with build-time bundle-size optimization.
- โA webpack5-based compiler with persistent caching, native mini-program compatibility, and npm-based subpackage output support.
- โSingle-file component (SFC) authoring, similar in shape to Vue's SFC format.
- โState management following the Vuex spec, with multi-instance store support and a separate Pinia-style store package.
- โCross-platform compilation: one codebase to WeChat, Alipay, Baidu, ByteDance, QQ, and JD mini-programs, a quick-app/Web target, and React Native (iOS/Android/Harmony).
Getting Started with Mpx
Install the CLI globally with `npm i -g @mpxjs/cli`, scaffold a project with `mpx create mpx-project`, then `cd mpx-project && npm i`. Run `npm run serve` for development or `npm run build` for a production build, then open the matching platform folder inside the generated `dist/` directory with your mini-program IDE (WeChat DevTools, etc.) to preview it. For a React Native target, pick an RN-enabled template when running `mpx create`, then use platform-specific scripts such as `npm run serve:ios`/`serve:android`/`serve:harmony` for development and `npm run build:ios`/`build:android`/`build:harmony` for production โ the README notes the exact script names depend on what the scaffold generates. RN output typically lands in `dist/react-native/` or wherever your RN container project's own convention points.
Developing with Mpx: Code Examples
The README's example is a single-file Mpx component: a `<template>` block using WeChat-style directives (`wx:style`, `wx:for`/`wx:key`, `wx:class`, `bindtap`, `wx:model` for two-way binding, `wx:ref`, and a dynamic `<component is>`), a `<script>` block that calls `createPage` from `@mpxjs/core` with `data`, `computed`, `watch`, event handlers, and an `onReady` lifecycle hook, and a `<style lang="stylus">` block. The same file checks `__mpx_mode__` to branch behavior per target platform (`wx`, `ali`, `harmony`). For React Native targets specifically, Mpx uses per-platform conditional-compilation files โ `.ios.mpx`, `.android.mpx`, `.harmony.mpx` โ and the README notes that if an `android` or `harmony` file is missing, the build falls back to that file's `.ios` version.
Why Choose Mpx for Cross-Platform Development?
- โSingle-file components with a Vue-like API (data, computed, watch, methods, lifecycle hooks) instead of hand-wiring three separate native mini-program files.
- โA genuinely small runtime โ 14KB compressed and gzipped, per the README โ plus webpack5-based build-size optimization for the compiled output.
- โStays close to each platform's native APIs and component model instead of emulating a browser DOM inside the mini-program runtime, per the README's own 'enhancement' design rationale, so existing native component libraries and tooling keep working.
- โOne React Native output path covers iOS, Android, and Harmony from the same Mpx source and compile config, with per-platform differences handled through conditional-compilation files.
- โApache-2.0 license.
- โTypeScript support built on ThisType for type inference inside SFCs, plus documented unit-test and E2E-test tooling.
Potential Considerations for Mpx
- โณDocumentation, the official site, and the primary support channels (WeChat and QQ groups) run Chinese-first per the README โ no English documentation is referenced in the facts available here.
- โณThe React Native build scripts shown in the README are described as indicative, since 'the exact script names depend on what the scaffold generates,' so the precise CLI surface for RN builds isn't fully pinned down in the docs.
- โณHarmony support only exists inside the React Native output path โ the README is explicit that it isn't a separate mini-program output target, so it's a variant of RN rather than an independent platform.
- โณDay-to-day production details โ deployment, CI, release cadence โ aren't documented in the README beyond the quick-start commands.
- โณThe community and third-party ecosystem around Mpx is much smaller than what surrounds Vue or React Native themselves.
Real-World Mpx Applications
- โขBuilding one codebase that ships to multiple mini-program platforms (WeChat, Alipay, Baidu, ByteDance, QQ, JD) without hand-porting templates per platform.
- โขExtending that same codebase into a Web build and React Native apps for iOS, Android, and Harmony, matching the output targets the README lists.
- โขMigrating an existing native mini-program incrementally, since the README documents progressive adoption and native-component support that let native code and Mpx code sit side by side.
- โขReusing an existing mini-program component library, analytics SDK, or other native tooling inside an Mpx project, since the README says Mpx stays compatible with native mini-program technical specs.
- โขBuilding internal mini-programs across multiple teams at a larger org, since the README documents cross-team development through packages and logic reuse through mixins.
Mpx Alternatives for Multi-Platform Development
Frequently Asked Questions About Mpx
Mpx compiles one codebase to WeChat, Alipay, Baidu, ByteDance/Toutiao, QQ, and JD mini-programs, to a quick-app/Web target, and to React Native apps for iOS, Android, and Harmony, per the README's output-platform table.
Mpx is released under the Apache-2.0 license and is free, open-source software, according to its GitHub repository.
Mpx supports TypeScript, using ThisType-based type inference inside single-file components, according to the README.
Mpx keeps its compressed, gzipped runtime around 14KB and pairs it with webpack5-based build-size optimization and template-driven dependency tracking, per the README's design notes, rather than emulating a full browser DOM inside the mini-program runtime.
Mpx documents progressive adoption and native-component support, so native mini-program components and Mpx components can be mixed within the same project.
Mpx's README describes its API as Vue-like โ data reactivity, computed properties, watch, and single-file components โ while still compiling down to each mini-program platform's native template and API surface instead of a browser DOM.
The problem it solves
Teams building for WeChat, Alipay, Baidu, and the other mini-program platforms usually end up either hand-maintaining near-duplicate template code per platform, or reaching for a web MVVM framework that gets translated down into the mini-program runtime โ an extra abstraction layer Mpx's own README argues against. Mpx's README frames its design choice as the opposite: build on each platform's native mini-program syntax first, then layer on Vue-like reactivity and a compiler that emits that same enhanced source to Web and React Native (iOS/Android/Harmony) too.
Who should try it โ and who should skip
Try Mpx if you're already building WeChat, Alipay, Baidu, ByteDance, QQ, or JD mini-programs and want single-file, Vue-like components instead of three separate native files per screen โ especially if you also need a Web or React Native (iOS/Android/Harmony) build from the same source. Skip it if you're not building for the mini-program ecosystem at all: the payoff is tied to that platform family, and the documentation and community support run Chinese-first.
Related repositories
Curious whether mpx is right for you?
Let ChatGPT, Claude, or Perplexity look into it โ click below and see what AI actually says about mpx.