Frontend Components
Relevant source files
The following files were used as context for generating this wiki page:
Furin frontend components manage the structure, metadata, and hydration of React applications. These components facilitate file-based routing with Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR).
Sources: README.md:1-5, packages/core/src/furin.ts:252-258
Core Document Components
The framework uses specialized components to define the HTML document shell and handle client-side hydration.
Document State and Provider
The DocumentProvider uses DocumentContext to distribute DocumentState throughout the component tree. This state includes asset information like build IDs, entry modules, and stylesheets.
Sources: packages/core/src/client/document.tsx:29-35
HeadContent
HeadContent renders metadata, styles, and scripts within the <head> of the document. It automatically injects a theme script that applies "light" or "dark" classes based on localStorage.
- Renders
<title>and<meta>tags. - Injects JSON-LD for structured data.
- Handles external stylesheets and inline styles.
Sources: packages/core/src/client/document.tsx:62-97
Scripts
The Scripts component manages the injection of framework-level JSON data and the client entry module. It renders script tags with IDs like __FURIN_DATA__ and __FURIN_SYNC__ to provide the client with the necessary hydration data.
Sources: packages/core/src/client/document.tsx:103-138
Component Architecture and Interleaving
Furin organizes components in a hierarchical tree where layouts wrap boundaries, and boundaries wrap subsequent segments.
Boundary Interleaving
The framework interleaves FurinErrorBoundary and FurinNotFoundBoundary at each segment depth that declares a convention file. The FurinErrorBoundary always wraps the FurinNotFoundBoundary at the same depth.
The following diagram shows the structural relationship between layouts, boundaries, and pages:
The diagram illustrates how boundaries sit inside layouts but wrap all deeper content, ensuring layouts persist when children throw errors.
Sources: packages/core/tests/rendering/errors/render-element-boundaries.test.tsx:9-25, packages/core/tests/client/link/link-boundaries.test.tsx:125-135
Development Components
Specific components and overlays provide feedback during the development process.
Dev Error Overlay
In development mode, Furin injects a shadow DOM overlay to display compilation and runtime faults. This overlay provides detailed stack traces, import chains, and source locations.
- WebSocket Connection: Connects to
/_furin/dev/errorsfor real-time updates. - Hydration Errors: Listens for
furin:hydrate-errorevents to display client-side mismatches.
Sources: packages/core/src/client/dev-error-overlay.js:33-52, packages/core/src/client/dev-error-overlay.js:203-219
Component Summary Table
| Component | Purpose | Source File |
|---|---|---|
HeadContent | Manages document metadata, theme scripts, and stylesheets. | document.tsx |
Scripts | Injects hydration data and the ESM entry module. | document.tsx |
FurinErrorBoundary | Catches React render errors and displays fallback UI. | boundaries.tsx |
FurinNotFoundBoundary | Handles not-found states at specific route depths. | boundaries.tsx |
FurinDocumentFallback | Provides a last-resort HTML shell if the root document fails. | document.tsx |
Sources: packages/core/src/client/document.tsx:62-149
Component Hydration Flow
The following sequence diagram represents the data flow from the server to the frontend components during hydration:
This diagram shows how HeadContent and Scripts collaborate to prepare the browser for React hydration.
Sources: packages/core/src/client/document.tsx:62-138
Conclusion
Frontend components in Furin ensure a consistent structure between server-rendered HTML and client-side React. By using a strictly interleaved architecture of layouts and boundaries, the framework provides robust error isolation and metadata management across SSR and SSG environments.