add-app-icon

Add App Icon

Icons live in assets/icons/apps/<slug>.svg (or .webp). The filename without the extension is the slug. assets/utils/appIcons.ts resolves an image reference to a slug.

Procedure

1. Find how the image resolves today. The resolver drops registry, tag and digest, then tries the image name and falls back to the namespace (linuxserver/sonarr tries sonarr). Distributor namespaces (DISTRIBUTORS) and generic names (GENERIC, e.g. server, app) are skipped. Suffixes like -server, -app, -alpine are stripped.

2. Get the icon from dashboard-icons. Prefer SVG, use WebP only when no SVG exists. Never use PNG (it is not globbed). Check the upstream tree rather than guessing URLs, since variants can exist in one format and not another:

   gh api 'repos/homarr-labs/dashboard-icons/git/trees/main?recursive=1' \
     --jq '.tree[].path' | grep -E '^(svg|webp)/<slug>(-light|-dark)?\.'
   

   slug=<slug>
   curl -fsSL -o assets/icons/apps/$slug.svg \
     https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/svg/$slug.svg
   

   If the SVG is over 20KB (wc -c < assets/icons/apps/$slug.svg), delete it and use the WebP below instead. An SVG that large is almost always a traced raster made of thousands of paths, not real vector artwork.

   Upstream WebPs are 128-4096px and often 20-180KB. Downscale to 64px tall, lossy, like every other WebP in the folder (they land around 1-3KB). cwebp and webpinfo ship in the webp package (brew install webp, apt install webp):

   curl -fsSL -o /tmp/$slug.webp \
     https://raw.githubusercontent.com/homarr-labs/dashboard-icons/main/webp/$slug.webp
   cwebp -quiet -resize 0 64 -q 80 -m 6 /tmp/$slug.webp -o assets/icons/apps/$slug.webp
   

   Look at the result before committing. Do not substitute the app's own favicon.svg when upstream has no SVG: those are often a PNG wrapped in an <image> tag, not vector artwork.

   If upstream has themed variants, add them too: <slug>-light.svg is artwork for dark backgrounds, <slug>-dark.svg is for light backgrounds. The base <slug>.svg is still required, since it is what the resolver checks for.

   Use the upstream slug as the filename. Do not rename it to match the image.

3. If the image name does not match the slug after step 1, add an entry to ALIASES in assets/utils/appIcons.ts, keyed by the lowercased image name or namespace:

   "signal-cli-rest-api": "signal",
   

   Do not alias a generic word or a distributor namespace. If a new distributor repackages other people's software, add it to DISTRIBUTORS instead.

4. Add a case to the iconSlugForImage test.each table in assets/utils/appIcons.spec.ts for every alias you added:

   ["bbernhard/signal-cli-rest-api:latest", "signal"],
   

5. Verify:

   TZ=UTC bun run test assets/utils/appIcons.spec.ts
   bunx prettier --write assets/utils/appIcons.ts assets/utils/appIcons.spec.ts
   

   Then check every icon in the folder, not only yours. This should print nothing; any WebP taller than 64px, any file that is not really a WebP, or any SVG over 20KB needs step 2 redone:

   sh -c 'for f in assets/icons/apps/*.webp; do
     h=$(webpinfo "$f" 2>/dev/null | awk "/Height:/{print \$2; exit}")
     [ "${h:-0}" -gt 0 ] || { echo "not a webp: $f"; continue; }
     [ "$h" -gt 64 ] && echo "${h}px tall: $f"
   done
   find assets/icons/apps -name "*.svg" -size +20k'
   

Rules

• One commit per batch, titled feat(icons): add icons for <apps>.
• Only well-known, publicly available images. No logos for private or internal images; users can already pick an existing icon with the dev.dozzle.icon=<slug> label, or hide a wrong guess with dev.dozzle.icon=none.
• Do not hand-edit upstream artwork beyond what the file needs to load. The WebP downscale in step 2 is the one exception.
• When the batch comes from GitHub issues, one PR per issue is fine; end each PR body with Closes #<issue>.