Adapting React Native to Mini‑Programs with the qrn‑remax‑unir Component Library

The qrn‑remax‑unir component library, created by QuNar's front‑end team, enables React Native (RN) code to run directly on H5 and multiple mini‑program platforms (WeChat, Alipay, etc.) by leveraging the Remax framework and a custom adaptation layer.

Multi‑end solution overview : The overall strategy combines three steps – (1) use react‑native‑web to adapt RN to H5, (2) build an RN‑compatible component set on top of Remax, and (3) employ Webpack to produce platform‑specific bundles.

Research on existing solutions : The team evaluated alita , which compiles JSX to WXML fragments and provides a mini‑React runtime. Although innovative, alita imposed limitations on RN APIs, required custom animation libraries, and only supported WeChat mini‑programs, so it was not adopted.

Remax principle : Remax implements a React renderer that collects UI change commands, builds a VNode tree, and renders it in the mini‑program environment. This runtime‑based approach offers full React ecosystem compatibility (hooks, Redux, etc.) but may have performance trade‑offs for dynamic templates.

Our adaptation scheme :

Map RN components to Remax equivalents (e.g., Text → Remax Text ).

Classify RN APIs into two groups: pure‑function APIs (e.g., Dimensions ) that are wrapped to call the corresponding mini‑program API, and UI‑component APIs (e.g., alert , ToastAndroid ) that are implemented as hidden components whose state is toggled via method calls.

Complex components are built from the adapted base components, ensuring that once the base set is complete, higher‑level RN components work out‑of‑the‑box.

Style handling :

Two approaches were considered – compile‑time extraction via Babel/Webpack plugins and runtime dynamic generation. The compile‑time method failed for dynamic values (e.g., device‑dependent dimensions). The runtime approach, inspired by react‑native‑web , parses RN style objects at runtime, converts class names and inline styles, and passes them to Remax components.

const convertStyle = (styles) => {
    const classList = [];
    const style = {};
    const convert = (value) => {
        if (typeof value === 'string') {
            classList.push(value);
        } else if (Array.isArray(value)) {
            value.forEach(item => convert(item));
        } else {
            value && Object.assign(style, inline(value));
        }
    };
    convert(styles);
    return { classList, style };
};

Example of compile‑time conversion (shown for illustration) and the resulting .wxss snippet:

.container-test {
    width: 100px;
    height: 100px;
}

Animation support : The library keeps RN animation APIs unchanged. An RN Animated.timing call is transformed into a mini‑program transition style (e.g., transition: 3000ms opacity cubic-bezier(0.42,0,1,1) ), with linear fallback for unsupported easing curves.

Animated.timing(
    this.state.opacity,
    {
        toValue: 1,
        duration: 3000,
        easing: Easing.ease
    }
).start();

Development workflow :

Install dependencies: yarn

Run development mode for RN/Web: yarn dev

Run development mode for WeChat mini‑program: yarn dev:wx (open ./dist/wechat in the mini‑program IDE).

The project provides a demo repository, documentation site, and a sample that showcases RN → Web → Mini‑Program compilation, illustrating the seamless cross‑platform development experience.

For more details, see the GitHub repository ( https://github.com/qunarcorp/qrn-remax-unir ), the demo ( https://github.com/qunarcorp/qrn-remax-unir-demo ), and the online documentation ( https://qunarcorp.github.io/qrn-remax-unir ).