0
# Rax
1
2
Rax is a universal React-compatible render engine that enables developers to build applications that run across multiple platforms including Web, Weex, Node.js, Alibaba MiniApp, and WeChat MiniProgram. It provides a React-like API with better performance and smaller bundle size (~6KB) while maintaining full API compatibility with React components and hooks.
3
4
## Package Information
5
6
- **Package Name**: rax
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support via @types/rax)
9
- **Installation**: `npm install rax`
10
- **Repository**: https://github.com/alibaba/rax
11
- **Documentation**: https://rax.js.org/
12
13
## Core Imports
14
15
```javascript
16
import { createElement, render, Component, useState, useEffect } from 'rax';
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { createElement, render, Component, useState, useEffect } = require('rax');
23
```
24
25
React compatibility imports:
26
27
```javascript
28
import { createElement, render, Component } from 'rax/dist/rax.js';
29
// or with compatibility layer
30
import Rax, { Children, isValidElement, createFactory, cloneElement } from 'rax/src/compat';
31
```
32
33
Additional utilities (from compatibility layer):
34
35
```javascript
36
import { Children, isValidElement, createFactory, cloneElement } from 'rax/src/compat';
37
// or as default export
38
const Rax = require('rax/src/compat');
39
// Rax.Children, Rax.isValidElement, etc.
40
```
41
42
## Basic Usage
43
44
```javascript
45
import { createElement, render, Component, useState } from 'rax';
46
import * as DriverDOM from 'driver-dom';
47
48
// Functional component with hooks
49
function Counter() {
50
const [count, setCount] = useState(0);
51
52
return createElement('div', null,
53
createElement('p', null, `Count: ${count}`),
54
createElement('button', {
55
onClick: () => setCount(count + 1)
56
}, 'Increment')
57
);
58
}
59
60
// Class component
61
class Greeting extends Component {
62
render() {
63
return createElement('h1', null, `Hello, ${this.props.name}!`);
64
}
65
}
66
67
// Render to DOM
68
render(
69
createElement('div', null,
70
createElement(Greeting, { name: 'World' }),
71
createElement(Counter)
72
),
73
document.body,
74
{ driver: DriverDOM }
75
);
76
```
77
78
## Architecture
79
80
Rax is built around several key components:
81
82
- **Element System**: Virtual DOM creation through `createElement` and element management
83
- **Component System**: Support for both functional and class-based components with lifecycle methods
84
- **Hooks System**: Complete React hooks compatibility (useState, useEffect, useContext, etc.)
85
- **Rendering Engine**: Universal renderer that works across platforms through driver specification
86
- **Context API**: Provider/Consumer pattern for state management across component trees
87
- **Platform Drivers**: Pluggable rendering backends for different platforms (DOM, Weex, etc.)
88
89
## Capabilities
90
91
### Element Creation and Management
92
93
Core virtual DOM element creation and manipulation functionality. Essential for all Rax applications.
94
95
```javascript { .api }
96
function createElement(type, config, ...children);
97
function Fragment(props);
98
function createRef();
99
function forwardRef(render);
100
function memo(type, compare);
101
```
102
103
[Element Creation](./element-creation.md)
104
105
### Component System
106
107
Class-based and functional component support with full lifecycle management and React compatibility.
108
109
```javascript { .api }
110
class Component {
111
constructor(props, context);
112
setState(partialState, callback);
113
forceUpdate(callback);
114
}
115
116
class PureComponent extends Component {
117
constructor(props, context);
118
}
119
```
120
121
[Components](./components.md)
122
123
### React Hooks
124
125
Complete React hooks implementation for state management and side effects in functional components.
126
127
```javascript { .api }
128
function useState(initialState);
129
function useEffect(effect, inputs);
130
function useContext(context);
131
function useRef(initialValue);
132
function useCallback(callback, inputs);
133
function useMemo(create, inputs);
134
function useReducer(reducer, initialArg, init);
135
function useLayoutEffect(effect, inputs);
136
function useImperativeHandle(ref, create, inputs);
137
```
138
139
[Hooks](./hooks.md)
140
141
### Context API
142
143
React-compatible context system for managing state across component trees without prop drilling.
144
145
```javascript { .api }
146
function createContext(defaultValue);
147
148
interface ContextObject {
149
Provider: ComponentClass;
150
Consumer: ComponentClass;
151
_contextID: string;
152
_defaultValue: any;
153
__getNearestParentProvider: Function;
154
}
155
```
156
157
[Context](./context.md)
158
159
### Rendering System
160
161
Universal rendering engine that works across multiple platforms through pluggable driver system.
162
163
```javascript { .api }
164
function render(element, container, options, callback);
165
function render(element, container, callback);
166
```
167
168
[Rendering](./rendering.md)
169
170
### React Compatibility Utilities
171
172
Additional utilities for React compatibility, including children manipulation and element validation functions.
173
174
```javascript { .api }
175
// From rax-children package
176
const Children: {
177
map(children, fn): Array;
178
forEach(children, fn): void;
179
count(children): number;
180
only(children): RaxElement;
181
toArray(children): Array;
182
};
183
184
// From rax-is-valid-element package
185
function isValidElement(object): boolean;
186
187
// From rax-create-factory package
188
function createFactory(type): Function;
189
190
// From rax-clone-element package
191
function cloneElement(element, props, ...children): RaxElement;
192
```
193
194
[React Compatibility](./react-compatibility.md)
195
196
### Version Information
197
198
Package version information for runtime version checking and debugging.
199
200
```javascript { .api }
201
// Package version string (from process.env.RAX_VERSION at build time)
202
const version: string;
203
```
204
205
### Internal Utilities (Advanced)
206
207
Low-level utilities exposed for advanced use cases and platform driver development. These are internal APIs that may change between versions.
208
209
```javascript { .api }
210
const shared: {
211
Host: Object; // Runtime state management
212
Instance: Object; // Instance management utilities
213
Element: Function; // Element constructor
214
flattenChildren: Function; // Children flattening utility
215
};
216
```
217
218
## Platform Support
219
220
Rax supports multiple platforms through its driver specification:
221
222
- **Web**: `driver-dom` for browser environments
223
- **Weex**: Native mobile app rendering
224
- **Node.js**: Server-side rendering
225
- **Alibaba MiniApp**: Alibaba's mini-program platform
226
- **WeChat MiniProgram**: WeChat's mini-program platform
227
228
## Types
229
230
```javascript { .api }
231
// Core element type
232
interface RaxElement {
233
type: string | Function;
234
key: string | null;
235
ref: Function | Object | null;
236
props: Object;
237
_owner: Component | null;
238
}
239
240
// Component props and context
241
interface ComponentProps {
242
[key: string]: any;
243
children?: RaxElement | RaxElement[];
244
}
245
246
interface ComponentContext {
247
[key: string]: any;
248
}
249
250
// Render options
251
interface RenderOptions {
252
driver: Object;
253
hydrate?: boolean;
254
parent?: RaxElement;
255
}
256
257
// Ref object
258
interface RefObject<T> {
259
current: T | null;
260
}
261
```