Hiccup

Hiccup is a lightweight, self‑hosted personal dashboard that turns any static web server into a fast, customizable start page. From a developer’s standpoint it is essentially a single‑page React application that reads its entire configuration from a JSON file (config.json). The app is intentionally stateless, making it ideal for static hosting environments such as GitHub Pages, Netlify, or any container that serves static assets. Because all state is persisted in the browser’s localStorage, the core logic remains on the client side, while developers can still provide remote configuration or plug in custom search providers via a small API surface.

Key Features

• Static Webpage – No backend required; the bundle is pure HTML/CSS/JS.
• Config‑as‑Code – The config.json drives links, categories, search providers, and UI options. Developers can version‑control these files or expose them through a simple HTTP endpoint.
• Drag & Drop UI – The editor supports drag‑and‑drop of links and images, enabling quick visual updates without touching JSON directly.
• Search Extensibility – Built‑in support for multiple search engines and the ability to register custom providers via a declarative JSON schema.
• Docker & PWA – A pre‑built Docker image (bleckbeard/hiccup) is available, and the app registers a service worker for offline use.

Technical Stack

The project’s minimal dependencies keep the bundle size under 200 KB, ensuring sub‑second load times even on mobile networks.

Core Capabilities

• Profile Management – Multiple profiles can be loaded by swapping the config.json or pointing to a remote URL (loadRemoteProfile). This allows distinct dashboards per user or device.
• Caching Strategies – Config files can be cached via HTTP cache headers, and the app respects Cache-Control to avoid unnecessary fetches.
• Keyboard Navigation – Full support for arrow keys, tabbing, and custom shortcuts (e.g., Ctrl+K to trigger search).
• Read‑Only Mode – Useful for public deployments; disables the editor while still rendering links.
• PWA Registration – Service worker registration enables “Add to Home Screen” functionality on mobile.

Deployment & Infrastructure

Because the application is stateless, it scales horizontally by simply serving more instances of the static build. Docker simplifies deployment:

docker run -p 80:80 bleckbeard/hiccup

For high‑traffic scenarios, a CDN (Cloudflare, Fastly) can cache the static assets globally. The only dynamic requirement is the optional remote config endpoint, which can be served by any lightweight HTTP server or even a serverless function.

Integration & Extensibility

• Custom Search Providers – Developers can inject new providers by adding a JSON entry with name, searchUrl, and optional icon.
• Webhook Support – While the core app does not expose a backend, developers can build a small proxy that accepts POST requests to update the config.json and triggers a rebuild or invalidates CDN caches.
• Plugin Hooks – The editor exposes onLinkAdd, onProfileSwitch callbacks that can be overridden to integrate analytics or authentication flows.

Developer Experience

• Configuration as Code – The JSON schema is well‑documented in the repo, making it trivial to integrate with CI pipelines or version control systems.
• Rich Documentation – The README covers installation, usage, and Docker deployment. Additional comments in the source code explain each component’s role.
• Community & Licensing – The project is MIT‑licensed, encouraging reuse. While the community is small, issues and pull requests are handled promptly on GitHub.

Use Cases

Advantages

• Zero Runtime Overhead – No Node.js or database required; the app runs entirely in the browser.
• Performance – Static assets are served from a CDN, and the React bundle is minified to deliver instant navigation.
• Flexibility – Developers can treat the dashboard as a UI component and embed it into larger applications or micro‑frontend architectures.
• Licensing – MIT license removes any commercial restrictions, making it suitable for internal tools or public-facing services.

In short, Hiccup offers a developer‑friendly, zero‑maintenance solution for creating fast, configurable start pages that can be versioned, containerized, and served from any static hosting platform.