How amardeepxy/rand_wallhaven works
1. What this repo is
- rand_wallhaven is a Node.js command-line wallpaper tool for Wayland desktops.
- Its purpose is to fetch a random wallpaper from Wallhaven and apply it through the local swww wallpaper daemon.
2. Top-level architecture
- The code is split into a small set of focused modules under app/.
- A build step produces dist/index.cjs, and the project is then compiled into a runnable CLI executable named wallhaven.
3. Main runtime boundary
- The app runs as a local CLI process.
- It depends on two outside systems:
- the Wallhaven web API for wallpaper source images
- the local swww binary/service for actually changing the desktop wallpaper
4. Entry/orchestration layer
- app/wallhaven.js appears to be the main application entrypoint and coordinator.
- This is where CLI arguments are likely interpreted and the sequence “choose image → apply wallpaper” is driven.
5. Wallhaven API subsystem
- app/wallhaven/client.js is the network client boundary.
- It encapsulates communication with Wallhaven rather than mixing HTTP logic into the rest of the app.
- This module is the main dependency on internet access and Wallhaven’s response format.
6. Wallpaper application subsystem
- app/swww/swww.js is the adapter around swww.
- It likely maps the app’s options, such as transition type and transition step, into the commands expected by swww.
- This keeps Wayland-specific wallpaper-setting logic isolated from image retrieval.
7. Shared utility layer
- app/utility/utility.js holds reusable helper logic used across the CLI.
- This kind of module typically contains common operations such as argument handling helpers, path/string helpers, or small transformation functions.
- It functions as the shared support layer between the orchestrator, API client, and wallpaper adapter.
8. Data flow through the app
- User runs the CLI with options like --transition-type wipe --transition-step 50.
- The main module resolves behavior, calls the Wallhaven client to get a random image, then passes the selected image plus transition settings to the swww wrapper.
- The final effect is a desktop wallpaper change on the local Wayland session.
9. Build and distribution path
- Source lives in app/.
- A build output is checked in or generated under dist/ as index.cjs.
- The project is then compiled into a standalone executable, which is how releases are distributed.
10. Repository contents that are not runtime-critical
- demo/ and the screenshots in the README are presentation assets.
- README.md documents installation, build, and usage, but it is not part of runtime behavior.
11. Important architectural constraint
- The project is not a general wallpaper engine; it is specifically a Wayland CLI wrapper around swww plus Wallhaven.
- So the key architecture diagram should show:
- user/CLI input
- Wallhaven API fetch
- local swww wallpaper application
- build packaging into a standalone executable
Main entry points: wallhaven.js Main app · client.js Wallhaven client · swww.js swww adapter · wallhaven wallhaven CLI
Components 10
App
Runtime source modules
- Main app · Coordinates random wallpaper selection and application
app/wallhaven.js - Wallhaven client · Fetches random wallpaper data from the Wallhaven API
app/wallhaven/client.js - swww adapter · Wraps the local swww wallpaper daemon and its options
app/swww/swww.js - Utilities · Common helper functions used across the app
app/utility/utility.js
Build
Packaged CLI output
- wallhaven CLI · Installed command that launches the application
app/wallhaven - Built bundle · Generated CommonJS runtime bundle for distribution
dist/index.cjs - Package config · Defines scripts and build/package metadata
package.json
External
Outside services and binaries
- User · Runs the CLI with wallpaper and transition options
- Wallhaven API · Remote image source for random wallpapers
- swww daemon · Wayland wallpaper service invoked by the adapter
Connections 12
- User → wallhaven CLI: run · User invokes the installed command
- wallhaven CLI → Built bundle: execute · The packaged bundle starts the runtime
- Built bundle → Main app: load · Bundled entrypoint resolves the main app logic
- Main app → Wallhaven client: fetch wallpaper · Orchestrator asks for a random Wallhaven image
- Wallhaven client → Wallhaven API: HTTP request · Client communicates with the external wallpaper API
- Main app → swww adapter: apply wallpaper · Orchestrator passes selected image and transition settings
- swww adapter → swww daemon: command · Adapter calls the local swww service/binary
- Main app → Utilities: helpers · Main flow reuses shared utility functions
- Wallhaven client → Utilities: helpers · Client may reuse shared transformations or parsing helpers
- swww adapter → Utilities: helpers · Wallpaper adapter may reuse shared helpers
- Package config → wallhaven CLI: builds · Package metadata produces the distributable CLI
- Package config → Built bundle: bundle output · Build script emits the runnable CommonJS artifact