Master Rax: From Basics to Advanced Development

Introduction

This article is aimed at beginners of Rax, presenting what Rax is, the development experience, and how to solve common Rax development problems. It aligns with the release of Rax 0.5 and updates older tutorials accordingly.

1. What is Rax

Rax is an open‑source project from Alibaba (https://github.com/alibaba/rax) that serves as a higher‑level DSL for Weex and is widely used within the company. It is a cross‑container, high‑performance, lightweight JavaScript framework based on React syntax, so React developers can quickly pick it up. Differences from React include:

No createClass() method. setState() is synchronous in Rax, whereas it is asynchronous in React. findDOMNode() can accept a string ID. PropTypes are only for React interface compatibility.

A minimal example can be tried in the Playground to experience Rax functionality.

2. Basic Knowledge

If you already use React, you already know how to use Rax.

JSX

Developers familiar with React will recognize JSX; Rax’s DSL syntax is built on React JSX and JSX is mandatory in Rax. JSX is a syntax extension that looks like XML and is essentially syntactic sugar for createElement() calls, supported by Babel.

<View style={styles.text}>
  <Text style={styles.title}>hello</Text>
</View>

Rax’s lifecycle mirrors React’s:

Mounting phase: componentWillMount, render, componentDidMount Updating phase: componentWillReceiveProps, shouldComponentUpdate, componentWillUpdate,

componentDidUpdate

class Hello extends Component {
  render() {
    return <Text>Hello {this.props.name}</Text>;
  }
}

Common Events

Click event : Use the Touchable component with an onPress handler. A 300 ms delay distinguishes click from long‑press on mobile.

<Touchable onPress={() => console.log('pressed')}>
  <Text>Touch</Text>
</Touchable>

Long‑press : <input> and <switch> components do not support click events.

Appear : The onAppear and onDisappear events let you run logic when an element becomes visible or hidden, useful for exposure tracking.

<View onAppear={(ev) => console.log('appear')} onDisappear={(ev) => console.log('disappear')}>
  <Text>Hello</Text>
</View>

Scroll events : ScrollView, RecyclerView, ListView, and WaterFall support onScroll, onEndReachedThreshold, and onEndReached.

Input events : TextInput supports onFocus, onBlur, and onInput.

<TextInput placeholder="Enter text to see events" autoFocus multiline
  onFocus={() => console.log('onFocus')}
  onBlur={() => console.log('onBlur')}
  onInput={() => console.log('onInput')} />

Gestures : Rax provides a binding‑based gesture system that outperforms React Native’s PanResponder.

Page events : viewappear and viewdisappear fire before page animations and when a page is about to close. They must be bound to the root element.

let weexDocument = typeof __weex_document__ === 'object' ? __weex_document__ : typeof document === 'object' ? document : {};
if (isWeex && weexDocument && weexDocument.body) {
  setNativeProps(findDOMNode(weexDocument.body), {style: {backgroundColor: 'yellow'}}, {
    onViewAppear: () => console.log('onviewappear'),
    onViewDisAppear: () => console.log('onviewdisappear')
  });
}

3. Rax Drivers

Driver‑weex

Device handling to smooth differences with web.

Provides setRem for base size calculation.

Transforms style attributes.

Supports many HTML‑like tags (span, p, img, button, video, etc.).

Driver‑browser

Device handling to smooth differences with Weex.

Flex‑layout support.

Web‑prefix handling for cross‑browser compatibility.

Driver‑server

Basic server‑side rendering support.

Driver‑webgl

Provides a tag‑based 3D scene description.

Wraps three.js core features (cameras, lights, geometries, etc.).

4. Rax Framework

Write Once, Run Everywhere! The framework abstracts native‑Web differences, exposing global APIs (window, XMLHttpRequest, WebSocket, etc.) and common components that map Weex tags to web implementations. It follows React Native conventions, encouraging the use of Touchable for clicks.

weex‑rax‑framework

Global window variable and method registration.

Cross‑page emitter communication.

Standard web APIs (fetch, URL, Event, etc.).

Weex-specific helpers (define, require, downgrade, env, data, config, …).

web‑rax‑framework

Polyfills such as Object.assign, Object.entries, Array.from, Number.isNaN.

Appear event simulation to align with Weex.

Built‑in modules.

5. Upper‑Layer System

Rax Framework follows W3C specifications and provides consistent global APIs across Weex and web, e.g.,

addEventListener('message', e => console.log('this data is', e.data))

and postMessage('{"hello":1}', '*'). These APIs are available on Weex versions ≥ 0.9.5 (Taobao ≥ 6.4.0).

6. Development Environment

rax‑cli

CLI commands are independent of Alibaba internal tools.

Projects build both web and Weex bundles.

Installation: npm install rax-cli -g Project initialization: rax init YourProjectName Start preview:

cd YourProjectName
npm run start

The generated bundle contains a comment // {"framework" : "Rax"} which is required for proper API injection.

7. Debug Environment

Local debugging

Use weex‑toolkit:

tnpm install -g weex-toolkit
weex debug -l

8. Release

Before publishing, test on all relevant environments (Weex Android/iOS, Web Android/iOS, various Taobao versions). Ensure compatibility, define rollout order, handle offline packages, and adopt a “force update + new bundle + full network” strategy for urgent fixes.

9. Full Example

The Rax website offers many demos and templates (order page, instant‑messaging page, retail app home, Taobao home, Q&A list) to help newcomers start building real projects.