Design and Architecture of the Hawaii SSR Framework for WeChat HandQ

1. Background of the Hawaii Framework Design

Web page rendering can be divided into client‑side rendering (CSR) and server‑side rendering (SSR). CSR became popular with AJAX and front‑back separation, improving development efficiency but requiring multiple client‑server interactions that hurt performance. SSR, by contrast, needs only a single request, reducing latency and often doubling performance.

Traditional SSR implementations using Java, C++, PHP face issues such as unclear template ownership, lack of front‑back code reuse, and high development cost. Node.js brought JavaScript to the server, enabling front‑back isomorphic development, but practical large‑scale adoption is challenged by front‑end developers' limited back‑end expertise.

Modern view‑layer frameworks like React and Vue address UI complexity but do not solve model‑layer data orchestration. The ideal SSR development experience should allow front‑back code and template reuse, hide server implementation details, and simplify model‑layer handling.

The Hawaii framework, built for WeChat HandQ, meets these goals by leveraging Node.js for isomorphic development, providing a programmable JSON‑based Request Description Specification (RDS) to describe complex data fetching logic.

2. Hawaii Framework Overview

The Hawaii framework consists of four main parts:

Client side: a Gulp‑based automation tool offering scaffolding, local server, and compilation.

Management side: page management, resource publishing, and key‑based monitoring.

Server side: a unified SSR service supporting BigPipe, multi‑dimensional monitoring, and disaster recovery.

Supporting tools: packet capture and debugging utilities.

Developers write RDS files while the rest of the workflow mirrors ordinary front‑end development. The directory structure is straightforward, and the RDS file, a programmable JSON document, can describe arbitrary parallel, sequential, and conditional requests.

Key RDS design elements include:

Top‑level fields.

Module definitions.

Request definitions within each module, which are recursively parsed on the server to produce JSON data for rendering.

After compilation, a page is split into header, footer, template, and RDS parts and uploaded to the management side. The management side publishes the page using a unique key, and the SSR service parses the RDS, performs recursive request resolution, and streams content using a BigPipe‑style approach.

Hawaii also supports three page versions for reliability:

Sync version (direct SSR) – the primary fast path.

Async version – generated at compile time, includes the front‑end engine and RDS, and fetches data from server APIs.

Disaster‑recovery version – static HTML generated by crawling the SSR service, without front‑end engine or RDS.

Exception handling follows a tiered strategy, and multi‑level monitoring (service, page, interface) ensures rapid detection and diagnosis of issues.

3. Comparison with Popular Frameworks

React/Vue

While React and Vue provide solutions for the view layer and support isomorphic rendering, they focus on UI complexity. Hawaii, by contrast, targets the model layer’s data orchestration, offering a lower‑level foundation that can later integrate React/Vue components.

GraphQL

Hawaii’s RDS enables single‑request data aggregation and on‑demand fetching similar to GraphQL, but without a type system. This trade‑off avoids the substantial redesign cost of introducing a type schema into large, existing codebases, making Hawaii a pragmatic alternative for complex enterprise applications.

The author notes that the framework was designed without prior knowledge of GraphQL, and future work may incorporate GraphQL‑like features.