nixos/docs/superpowers/plans/2026-04-23-homepage-widgets.md

Homepage Widgets Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a my.homepage.widgets NixOS option so widgets can be declared in the homepage module and contributed from other modules, mirroring how my.homepage.services works today.

Architecture: Add a my.homepage.widgets option (typed listOf attrs since widget shapes vary by type) to the homepage module, import a manual-widgets.nix for ad-hoc definitions, merge both and pass to services.homepage-dashboard.widgets. Add starter widgets in machines/jupiter/environments.nix to confirm the wiring works end-to-end.

Tech Stack: Nix, NixOS module system, gethomepage.dev (services.homepage-dashboard)

---

File Map

Action	File	Responsibility
Modify	modules/environments/homepage/default.nix	Add my.homepage.widgets option + wire to dashboard
Create	modules/environments/homepage/manual-widgets.nix	Empty list for ad-hoc widgets (parallel to manual-services.nix)
Modify	machines/jupiter/environments.nix	Declare starter widgets to verify the feature end-to-end

---

Task 1: Add my.homepage.widgets option to the homepage module

Files:

• Modify: modules/environments/homepage/default.nix

• Create: modules/environments/homepage/manual-widgets.nix

• Step 1: Create manual-widgets.nix — empty list, same pattern as manual-services.nix

# modules/environments/homepage/manual-widgets.nix
[ ]

• Step 2: Add manualWidgets import in the let block of default.nix

Current let block (lines 7–42) ends with homepageServices. Add one line after manualServices:

  manualServices = import ./manual-services.nix;
  manualWidgets = import ./manual-widgets.nix;

• Step 3: Add the my.homepage.widgets option

After the closing brace of options.my.homepage.services (line 80), add:

  options.my.homepage.widgets = with lib; mkOption {
    type = types.listOf types.attrs;
    default = [ ];
    description = "Widget definitions passed directly to services.homepage-dashboard.widgets. Each entry is an attrset like { resources = { cpu = true; memory = true; }; }.";
  };

• Step 4: Wire widgets to the dashboard in the config block

The config block currently sets services = homepageServices ++ manualServices;. Add widgets:

  config = lib.mkIf cfg.enable {
    services.homepage-dashboard = {
      enable = true;
      listenPort = dashboardPort;
      allowedHosts = "${dashboardHost}:${toString dashboardPort},localhost:${toString dashboardPort},127.0.0.1:${toString dashboardPort},jupiter.solar.internal:${toString dashboardPort}";
      bookmarks = import ./bookmarks.nix;
      services = homepageServices ++ manualServices;
      widgets = config.my.homepage.widgets ++ manualWidgets;
    };
    # ... rest of config unchanged
  };

• Step 5: Build to check for eval errors (no switch yet)

nixos-rebuild build --flake /Users/finnmarkwitz/development/nixos#jupiter 2>&1 | tail -20

Expected: build succeeds with no errors (widgets list is empty, so no visible change yet).

• Step 6: Commit

cd /Users/finnmarkwitz/development/nixos
git add modules/environments/homepage/default.nix modules/environments/homepage/manual-widgets.nix
git commit -m "feat: add my.homepage.widgets option to homepage module"

---

Task 2: Add starter widgets in environments.nix

Files:

• Modify: machines/jupiter/environments.nix

• Step 1: Add my.homepage.widgets to environments.nix

Add the following after the my.profiles block (e.g. after line 39, before the my.hardware block):

  my.homepage.widgets = [
    {
      search = {
        provider = "google";
        target = "_blank";
      };
    }
    {
      resources = {
        cpu = true;
        memory = true;
        disk = "/";
        cacheInterval = 5000;
      };
    }
    {
      datetime = {
        text_size = "xl";
        format = {
          timeStyle = "short";
          dateStyle = "short";
          hour12 = false;
        };
      };
    }
  ];

• Step 2: Build to confirm eval

nixos-rebuild build --flake /Users/finnmarkwitz/development/nixos#jupiter 2>&1 | tail -20

Expected: build succeeds.

• Step 3: Switch and verify visually

sudo nixos-rebuild switch --flake /Users/finnmarkwitz/development/nixos#jupiter

Open http://jupiter.solar.internal:8082 (or http://localhost:8082) in a browser.

Expected: search bar, CPU/memory/disk resource monitor, and date/time widget appear at the top of the dashboard.

• Step 4: Commit

cd /Users/finnmarkwitz/development/nixos
git add machines/jupiter/environments.nix
git commit -m "feat: add starter homepage widgets (search, resources, datetime)"

---

Verification Checklist

• nixos-rebuild build passes with no eval errors
• Dashboard at :8082 shows widgets at top of page
• Existing services and bookmarks are unchanged
• Other modules can now contribute widgets via my.homepage.widgets = [ ... ]; in their config block