$ show gethomepage/homepage
This repository hosts Homepage, a self-hosted dashboard application for homelab and server enthusiasts. Built with Next.js and React, it aggregates data from over 100 external services (media servers, download clients, network tools, system monitors) via a centralized proxy architecture. The system is configuration-driven: users define services, bookmarks, widgets, and settings in YAML files, optionally extended via Docker labels or Kubernetes ingress annotations. A key architectural pattern is the widget system, where each integration consists of a React component, a proxy handler (handling authentication, session management, and data transformation), and a widget metadata file. The backend API routes handle proxying, caching, authentication (NextAuth with OIDC/password), Docker/Proxmox stats, weather, stocks, and an MCP endpoint for AI-assisted configuration. The frontend uses SWR for client-side data fetching, Tailwind CSS for theming, and i18next for internationalization (20+ languages). The codebase exhibits solid engineering practices: comprehensive test coverage (Vitest), CI/CD pipelines (GitHub Actions), Docker multi-arch builds, and extensive documentation. However, the large widget surface introduces duplication in authentication and proxy logic, and some patterns (in-memory caching, version-specific endpoints) represent maintenance risks. Overall, this is a well-crafted application for its domain, offering high customizability and a clean plugin-style architecture.
The LLM identified 5 files worth highlighting for reuse:
A robust HTTP proxy utility that handles keep-alive agents, custom DNS lookup fallback (critical for Alpine/musl compatibility), redirect following, cookie management via CookieJar class, and gzip decompression. Isolated and reusable for any Node.js service needing to proxy requests to external APIs with custom DNS or cookie persistence.
A generic credentialed proxy handler factory that manages authentication headers (Basic, Bearer, custom tokens), caches session tokens with TTL in memory, and automatically retries on 401/403 responses. Demonstrates a clean pattern for proxying APIs that require login, with configurable token extraction and error handling. Reusable for any external API integration needing credential support.
A highlight evaluation system that parses user-defined rules (numeric comparisons, string matching, boolean checks) against widget data and returns CSS class names for conditional styling. Supports localized number parsing (comma/dot) and complex rule composition. Extracted as a pure utility function, it can power dynamic styling in any data-driven UI without being tied to the dashboard's widget structure.
A centralized configuration loader that reads YAML files from a config directory, substitutes environment variables (HOMEPAGE_VAR_*, HOMEPAGE_FILE_*) and system user/group names, and provides a consistent API for accessing settings, services, bookmarks, widgets, and Docker/Kubernetes configs. Includes skeleton file creation, directory detection, and caching. The pattern of composable, environment-aware config loading is widely applicable to any self-hosted application.
A reusable widget container component that renders child blocks with field filtering, error states, loading placeholders, and highlight support. It automatically limits displayed fields to those specified in the widget config, handles aliasing (e.g. hoarder→karakeep), and integrates with the highlight context for dynamic styling. Extracting this component and its companion Block component provides a portable dashboard widget framework.