Client & Routing Overview
Understand how Dinou handles the browser-side SPA runtime, routing pipelines, navigation states, and the separation of success and error hydration lifecycles.
Client Subsystem Paths:
• Success Hydration Entry:./dinou/core/client.jsx/client-webpack.jsx
• Recovery Hydration Entry:./dinou/core/client-error.jsx/client-error-webpack.jsx
• Router Context & Hooks:./dinou/core/navigation.js/navigation-utils.js
• Link Click Hijacking:./dinou/core/link.jsx
• Server Functions Connection:./dinou/core/server-function-proxy.js
💡 Overview
Dinou provides a Single Page Application (SPA) user experience. When a browser requests a page, the server streams pre-rendered HTML. Once loaded, browser-side JavaScript hydrates the document nodes, hooks the router navigation context, intercepts anchor clicks to bypass browser reloads, and fetches incremental React Server Component (RSC) Flight streams dynamically to update the viewport.
To maintain optimized performance and avoid hydration mismatches, Dinou separates standard client operations from crash recovery flows using two distinct runtime systems:
- SPA Hydration (
client.jsx): Bootstrapped on successful page loads. It handles normal navigation transitions, scroll restoration, history state tracking, and Server Functions proxies. - Recovery Hydration (
client-error.jsx): Bootstrapped only when the server encounters a crash or compilation error during SSR. It displays the crash stack overlay, posts trace details back to the compiler, and provides mechanisms to safely navigate back to working states.
📂 Subsystem Files & Architecture
The Client & Routing subsystem consists of several tightly integrated files:
1. Hydration Entries (client.jsx & client-error.jsx)
These serve as the main compilation targets for bundlers, outputting main.js and error.js respectively. They invoke React 19's hydrateRoot to take ownership of the DOM.
2. Navigation context (navigation.js & navigation-utils.js)
Defines the RouterContext that propagates the current route path and transition state down the React component tree. It exports standard hooks like useRouter(), usePathname(), useSearchParams(), and useNavigationLoading().
3. Click interceptor (link.jsx)
Defines the client-side <Link> element that renders plain HTML anchors (<a>) for SEO crawlers but intercepts left-clicks in the browser to perform smooth SPA route transitions.
4. Server Functions Connection (server-function-proxy.js)
Intercepts invocations to functions containing the "use server" directive, serializing argument arrays or form data into HTTP POST requests sent to the server Function endpoint (/____server_function____).
⚖️ Success vs. Error Hydration
Although both files boot the client app, their initialization pathways and payload request methods diverge significantly:
| Feature | SPA Hydration (client.jsx) | Recovery Hydration (client-error.jsx) |
|---|---|---|
| Initial Load URL | /____rsc_payload____ + route | /____rsc_payload_error____ + route |
| HTTP Method | GET | POST |
| Initial Body | None | JSON error details (message, name, stack) |
| Global Window States | None required | Reads window.__DINOU_ERROR_MESSAGE__ / STACK |
| Compilation Trigger | Reads static or dynamic RSC | Compiles error component boundary JIT |
❓ Why Separate Hydration Entries?
Dinou isolates client.jsx from client-error.jsx during build compilation rather than merging them into a single file with conditional branches. This decision addresses key performance and structural requirements:
- Production Bundle Optimization: If combined, every successful user visit would download, parse, and evaluate scripts dedicated exclusively to compiling error stacks and managing crash states. Keeping the primary
main.jsbundle free of recovery code ensures fast load times. - Clean Separation of Concerns:
client.jsxhandles dynamic cookies, transition indicators, scroll preservation, and Actions streaming.client-error.jsxhas a single focus: displaying error diagnostics to developers and POSTing traceback metadata to compile recovery pages. - Avoiding Hydration Mismatches: React 19 expects the server-rendered HTML nodes to align exactly with the initial client-side virtual DOM during hydration. When a page has crashed, the server outputs error layouts. Using separate entry scripts prevents React from attempting to hydrate standard components over a crashed HTML container, which would trigger mismatch faults and repaint cycles.
- Security Boundaries: In production environments, verbose error traces should be hidden to prevent path leaks. Isolating the recovery runtime lets the bundler generate a secure, stripped-down
error.jswhile keeping dev stack trace overlays separated.