How Rax Bridges Web and Native: Inside the Weex-Powered Cross‑Platform Engine

Introduction

Rax is a cross‑container solution that lets developers avoid learning the specifics of iOS and Android. Since most Rax users are front‑end engineers, this article introduces the native side of Rax to help front‑end developers understand how it works.

Rax = RN Syntax + Weex Capability

Rax uses a React‑like syntax similar to React Native (RN) and is built on top of Weex. It aims to align closely with RN while providing additional cross‑platform features.

Rax vs React Native

Both Rax and RN use React abstractions to render native UI components (e.g., View instead of div, Image instead of img). Unlike RN, which focuses on “learn once, write anywhere,” Rax also emphasizes “learn once, write once” across web and native.

Rax vs Weex

Rax’s native implementation relies on Weex, a lightweight mobile cross‑platform solution. Weex: write once run anywhere The development workflow is:

Developers write Weex DSL (Vue/Rax).

A transformer converts the DSL to pure JavaScript.

The client parses the JavaScript and renders the UI.

Server side transforms DSL to JS and distributes it; client side handles rendering via a JS framework (main.js) and a native render engine. The V8 engine has been fully replaced by JavaScriptCore (JSC).

Framework Initialization

Weex runtime initialization includes:

Native initialization (JS framework) via initSDKEnvironment.

Extending JSContext with global APIs such as name and WXEnvironment.

Registering global functions and modules (e.g., Native, component) through WXBridgeContext.

Evaluating the framework JavaScript code.

Business Bundle Initialization

WXSDKInstance renderWithURL

injects the bundle URL. WXBridgeContext callJSMethod invokes createInstance with the bundle script.

Checks if the framework is ready before creating the instance.

Executes createInstance from weex‑framework.js, which calls the Rax window API.

The UI creation and destruction are driven by native code calling JavaScript through JavaScriptCore.

Weex Virtual‑DOM

Weex implements a virtual‑DOM layer that lets JavaScript control native views. It simplifies the traditional HTML DOM:

Only Element and Comment node types are kept.

Only attributes (no properties) are retained, with a special style attribute.

Event model is DOM Level 0 (no capture or bubbling).

Each page’s document.body must be created manually as scroller, div, or list.

Weex vs Web Differences

Layout

Weex uses Flexbox as the sole layout model; developers cannot use float and must be cautious with absolute positioning for long lists.

Style Limitations

Styles are scoped to the component.

Styles cannot be inherited.

Text‑related styles (e.g., fontSize) only apply to Text tags.

Only a subset of CSS properties is supported (e.g., no z-index).

Units

rem

: Recommended unit; equivalent to Weex’s px (page divided into 750 parts). wx: Weex‑specific unit, independent of pixels. px or no unit: Scaled according to screen width versus 750.

List Cells

Android list cells may clip overflow content; absolute positioning can cause truncation, unlike iOS.

Scrolling Containers

ScrollView → Weex slider (vertical/horizontal).

RecyclerView → Weex list (recyclable long list).

ListView → wrapper of RecyclerView, comparable to RN’s ListView.

WaterFall → extension of list.

TemplateList → recycler-list, high‑performance templated list.

RecyclerView Details

Rax’s RecyclerView is a high‑performance, recyclable long list implemented by Weex’s list. On Android it maps to the native RecyclerView component; on iOS it maps to UITableView. Cells with the same scopeValue can be reused via a ViewHolder‑like mechanism.

Images

Width and height must be specified; otherwise the image height defaults to 0 and causes layout jitter.

Weex provides built‑in lazy loading; background images are not supported.

For GIFs, set quality='original' to prevent CDN optimization.

Events

Weex supports a limited set of DOM 0 events (no capture or bubbling). Special events like appear and page differ from traditional web events.

Built‑in Modules

Weex offers modules such as animation, WebSocket, picker, meta, clipboard, dom, modal, navigator, storage, stream, webview, globalEvent, etc. In Rax they are used like:

let dom = require('@weex-module/dom');
 dom.getComponentRect('viewport', e => {
   console.log(e.result, e.size);
 });

Conclusion

Developing with Rax differs from traditional web development in many ways. Understanding the underlying mechanisms—such as the Weex virtual‑DOM, layout constraints, unit system, and native rendering pipeline—helps developers troubleshoot issues and make the most of Rax’s cross‑platform capabilities.