React UI & Islands
Relevant source files
The following files were used as context for generating this wiki page:
StatusBeam utilizes a "React Islands" architecture within an Astro-based framework to provide an interactive, high-performance status page. By default, the site ships zero JavaScript, hydrating only specific components (Islands) that require client-side interactivity, such as charts, tooltips, and theme toggles.
The UI is built using shadcn/ui components and Tailwind CSS, ensuring a modern aesthetic that remains functional even when javascript is disabled for the static portions of the page. The system is designed to be "CDN-native," rendering at the edge on Cloudflare Workers.
Sources: README.md:38-46, ARCHITECTURE.md:15-19, apps/web/astro.config.ts:16-18
Architectural Overview
StatusBeam's frontend architecture follows the Astro Island pattern. Most of the status page is rendered as static HTML on the server (Astro SSR), while interactive elements are "opted-in" to React hydration.
The diagram shows the separation between static HTML rendered at the edge and interactive React islands hydrated in the browser.
Sources: README.md:131-140, ARCHITECTURE.md:88-93
Island Hydration Strategy
The project uses the @astrojs/react integration to manage React components. Components like StatusList, ResponseChart, and ThemeToggle are specifically designated for hydration to enable features like:
- Expandable response-time sparklines.
- Hoverable 90-day uptime bars with tooltips.
- Client-side theme switching (Dark/Light mode).
Sources: apps/web/astro.config.ts:21, apps/web/src/components/StatusList.tsx:28-32, README.md:135-139
Core UI Components
Status List and Rows
The StatusList component acts as the primary container for service statuses. It maps through a SiteSummary[] array to render individual StatusRow components. Each row includes a status dot, service name, uptime percentage, and an expandable chart.
| Component | Purpose | Key Logic |
|---|---|---|
StatusList | Container for all service cards | Uses TooltipProvider and maps SiteSummary data. |
StatusRow | Displays individual service state | Manages open state for response-time chart expansion. |
UptimeTimeline | 90-day visual history | Renders colored bars representing daily status. |
Sources: apps/web/src/components/StatusList.tsx:1-112
Visualization & Charts
Interactive data visualization is handled by Recharts within React islands. The ResponseChart component provides a compact area chart (sparkline) showing response times over a recent window.
This flow illustrates how raw site summary data is processed into statistical metrics and a visual chart.
Sources: apps/web/src/components/ResponseChart.tsx:1-98
UI Primitives (shadcn/ui)
The project utilizes a local version of shadcn/ui components, allowing for full customization. These are located in apps/web/src/components/ui/.
- Card: Provides the base layout structure for status components with configurable sizes (
default,sm). - Tooltip: Utilizes Radix UI primitives to show detailed uptime breakdowns.
- Badge: Used for status pills (e.g., "Operational", "Degraded").
Sources: apps/web/src/components/ui/card.tsx:5-30, apps/web/src/components/StatusList.tsx:8-15
State and Severity Management
StatusBeam uses a unified severity system to drive UI colors and tokens across components.
| Severity | CSS Variable / Token | Status Meaning |
|---|---|---|
operational | --status-operational | All systems functioning normally. |
degraded | --status-degraded | Service is slow or partially impaired. |
partial_outage | --status-partial | Significant parts of service are down. |
major_outage | --status-major | Primary service functionality is lost. |
maintenance | --status-maintenance | Planned service work in progress. |
Sources: apps/web/src/components/StatusList.tsx:17-25, README.md:154-162
Code Snippet: Severity Styling
const STYLE = {
operational: { dot: 'bg-status-operational', badge: 'border-status-operational/40 text-status-operational' },
degraded: { dot: 'bg-status-degraded', badge: 'border-status-degraded/40 text-status-degraded' },
// ... other severities
} as const;
const severity = toSeverity(site.status);
const style = STYLE[severity];
Sources: apps/web/src/components/StatusList.tsx:18-25, apps/web/src/components/StatusList.tsx:34-35
Conclusion
The React UI & Islands implementation in StatusBeam balances the need for a highly resilient, static status page with the interactive requirements of modern monitoring tools. By utilizing Astro Islands, the project ensures that the core status information remains accessible even if client-side scripts fail, while providing a rich user experience for those with modern browsers.