homepage-blocky-widget/INSTALL.md

Installation

These files integrate as a standard service widget into the Homepage dashboard source. Homepage has no plugin system — you need to patch the source and rebuild.

1. Copy widget files

cp -r src/widgets/blocky /path/to/homepage/src/widgets/

2. Register the widget

src/widgets/widgets.js — add import and export:

import blocky from "./blocky/widget";
// ... existing imports ...

export default {
  blocky,
  // ... existing widgets ...
};

src/widgets/components.js — add dynamic import:

const components = {
  blocky: dynamic(() => import("./blocky/component")),
  // ... existing components ...
};

3. Add translations

In public/locales/en/common.json, merge the contents of translations/en.json into the top-level object. Repeat for any other locale files you use.

4. Homepage config

# services.yaml
- Infrastructure:
    - Pi DNS:
        href: http://10.0.50.5:4000
        description: DNS ad-blocker
        icon: blocky.png
        widget:
          type: blocky
          url: http://10.0.50.5:4000

What the widget shows

Field	Source metric
Status	blocky_blocking_enabled (Enabled / Disabled)
Blocked Domains	blocky_denylist_cache_entries{group="ads"}
Total Queries	blocky_cache_hits_total + blocky_cache_misses_total
Cache Hit Rate	hits / (hits + misses) × 100

Data is pulled from Blocky's Prometheus /metrics endpoint — the only source that exposes query counts. The REST /api/blocking/status endpoint only returns the blocking toggle state.

Upstream

There is an open feature request at https://github.com/gethomepage/homepage/discussions/2732 (currently 8 upvotes — Homepage requires 20 before considering a PR). Once it crosses that threshold, this widget can be submitted as a PR to the official repo.