theme.park

theme.park is a self‑hosted, CSS‑only theming engine that injects custom styles into any web application. Rather than reimplementing entire UIs, it serves a collection of ready‑made themes that can be applied to popular media and automation stacks such as Radarr, Sonarr, Overseerr and many others. The project is built to be lightweight, making it ideal for running inside Docker or on bare‑metal servers where resources are at a premium.

Technical Stack & Architecture

• Core Runtime: A minimal Node.js/Express service that hosts static CSS bundles and exposes a REST API for theme discovery. The server runs on port 8080 by default but can be overridden via environment variables.
• Storage: Themes are stored as plain files in a mounted volume (/app/themes). No database is required; the file system itself acts as the data store, which simplifies scaling and backup.
• Containerization: A Docker image (gilbn/theme.park) is published on GitHub Packages and Docker Hub, with a docker-compose example that mounts the theme directory and exposes the service to reverse proxies.
• Reverse‑Proxy Compatibility: The README lists extensive support for Nginx, Apache, Caddy and Traefik. By configuring a sub‑filter or path rewrite (e.g., /theme.css), the CSS can be injected into any target application without modifying its source code.

Core Capabilities & APIs

• Theme Registry API: GET /api/themes returns a JSON array of available themes, each containing metadata such as name, description, and compatible applications. This endpoint can be consumed by front‑end dashboards or CI pipelines to dynamically list themes.
• Theme Retrieval: GET /api/themes/:name.css streams the raw CSS file, allowing client applications to fetch and apply it on demand.
• Webhooks & Events: Although the core service is stateless, developers can hook into its lifecycle by exposing a webhook endpoint (/webhook) that receives POST payloads when a theme is updated or deleted.
• Extensibility: Themes can be added by simply dropping a .css file into the mounted volume. The API auto‑detects new files, eliminating the need for restarts.

Deployment & Infrastructure

• Self‑Hosting: Requires only Docker or a node environment. The service can be deployed on any Linux distribution, Windows Server (via WSL), or macOS.
• Scalability: Since the service is stateless and file‑based, horizontal scaling is trivial—spin up multiple replicas behind a load balancer. Caching can be handled by the reverse proxy to reduce disk I/O.
• Resource Footprint: The Node.js process consumes ~30 MiB of RAM, and the total disk usage scales linearly with the number of themes (≈ 5 MiB per theme on average).

Integration & Extensibility

• Plugin System: While the core does not ship a plugin API, developers can extend it by wrapping the service in a custom middleware that injects additional CSS or modifies responses on the fly.
• Customization: Themes support CSS variables and custom properties, allowing downstream applications to override colors without touching the original file.
• Community Themes: The project hosts a curated list of community‑contributed themes. Pull requests are encouraged, and each theme includes documentation hosted on docs.theme-park.dev.

Developer Experience

The project offers comprehensive, API‑first documentation (https://docs.theme-park.dev) that covers installation, configuration, and advanced usage patterns. The GitHub repository is actively maintained with a responsive issue tracker and Discord community for real‑time support. The open‑source license (MIT) removes any commercial restrictions, encouraging adoption in both personal and enterprise environments.

Use Cases

1. Media Center Customization: Quickly switch the look of Radarr, Sonarr, or Plex by pulling a theme from the registry.
2. Feature‑Rich Dashboards: Embed CSS into custom dashboards or monitoring tools without rewriting UI components.
3. Multi‑Tenant Environments: Deploy separate instances per tenant, each serving a distinct set of themes via isolated volumes.
4. Rapid Prototyping: Use theme files as a sandbox for experimenting with CSS without altering application code.

Advantages

• Zero Dependencies: No need for a database or complex build pipelines; themes are just files.
• Fast Iteration: Add, remove, or update a theme by editing the file system; changes propagate instantly.
• Lightweight Runtime: Minimal overhead makes it suitable for edge devices or low‑budget VPS plans.
• Open Source & Community‑Driven: Transparent development, frequent updates, and a growing library of themes ensure long‑term viability.

In summary, theme.park offers developers a pragmatic, low‑friction solution for styling any web application. Its file‑based architecture, API surface, and container‑friendly design make it an attractive choice for projects that need quick theming without the cost of full UI rewrites.