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
```