@@ -0,0 +1,164 @@
# 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`
``` nix
# modules/environments/homepage/manual-widgets.nix
[ ]
```
- [ ] **Step 2: Add `manualWidgets` import in the `let` block of `default.nix` **
Current `let` block (lines 7– `homepageServices` . Add one line after `manualServices` :
``` nix
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:
``` nix
options . my . homepage . widgets = with lib ; mkOption {
type = types . listOf types . attrs ;
default = [ ] ;
description = " W i d g e t d e f i n i t i o n s p a s s e d d i r e c t l y t o s e r v i c e s . h o m e p a g e - d a s h b o a r d . w i d g e t s . E a c h e n t r y i s a n a t t r s e t l i k e { r e s o u r c e s = { c p u = t r u e ; m e m o r y = t r u e ; } ; } . " ;
} ;
```
- [ ] **Step 4: Wire widgets to the dashboard in the `config` block **
The `config` block currently sets `services = homepageServices ++ manualServices;` . Add `widgets` :
``` nix
config = lib . mkIf cfg . enable {
services . homepage-dashboard = {
enable = true ;
listenPort = dashboardPort ;
allowedHosts = " ${ dashboardHost } : ${ toString dashboardPort } , l o c a l h o s t : ${ toString dashboardPort } , 1 2 7 . 0 . 0 . 1 : ${ toString dashboardPort } , j u p i t e r . s o l a r . i n t e r n a l : ${ 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) **
``` bash
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 **
``` bash
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):
``` nix
my . homepage . widgets = [
{
search = {
provider = " g o o g l e " ;
target = " _ b l a n k " ;
} ;
}
{
resources = {
cpu = true ;
memory = true ;
disk = " / " ;
cacheInterval = 5000 ;
} ;
}
{
datetime = {
text_size = " x l " ;
format = {
timeStyle = " s h o r t " ;
dateStyle = " s h o r t " ;
hour12 = false ;
} ;
} ;
}
] ;
```
- [ ] **Step 2: Build to confirm eval **
``` bash
nixos-rebuild build --flake /Users/finnmarkwitz/development/nixos#jupiter 2>& 1 | tail -20
```
Expected: build succeeds.
- [ ] **Step 3: Switch and verify visually **
``` bash
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 **
``` bash
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
marthsincemelee