Automate Favicon Generation with the JAD Local Runner

Check the runner is up before dispatching

Hit the health endpoint first so your script fails fast with a clear message if the runner isn't paired/running.

# health check
curl -fsS http://127.0.0.1:9789/v1/health || {
  echo 'JAD runner not reachable on :9789 — start/pair it'
  exit 1
}

Hash-on-change guard

Only regenerate when brand.svg actually changed. Cache the hash between runs.

NEW=$(sha256sum public/brand.svg | cut -d' ' -f1)
OLD=$(cat .favicon.hash 2>/dev/null || echo none)
if [ "$NEW" = "$OLD" ]; then
  echo 'brand.svg unchanged — skipping favicon build'
  exit 0
fi

Dispatch the job to the local runner

POST the SVG as form-data. No options field is needed — the tool has none. The runner writes the ZIP to disk and returns its path.

curl -fsS \
  -F 'files=@public/brand.svg;type=image/svg+xml' \
  http://127.0.0.1:9789/v1/tools/svg-favicon-master/run \
  -o runner-response.json

# runner-response.json → { outputPath, filename, sizeBytes, ... }

Unpack into public/ and record the hash

Extract the package next to your other static assets, then persist the hash so the next build can skip.

OUT=$(node -e "process.stdout.write(require('./runner-response.json').outputPath)")
unzip -o "$OUT" -d public/
sha256sum public/brand.svg | cut -d' ' -f1 > .favicon.hash
echo 'favicons regenerated into public/'

Wire it into a prebuild hook

Run the script before every build; the hash guard makes it a no-op when the brand is unchanged.

// package.json
{
  "scripts": {
    "prebuild": "bash scripts/generate-favicons.sh",
    "build": "next build"
  }
}

// In Next.js App Router, reference the files via metadata:
// icons: { icon: '/favicon.svg', apple: '/icon-180.png' }

Favicon Master is not in the server-safe SVG slug set, so the hosted engine throws 'is not exposed via the API — it requires browser-side processing (DOM, Canvas…)'. Automate via the local runner or the browser, not a remote endpoint.

If the daemon isn't up on 127.0.0.1:9789, the POST fails to connect. In the web app this silently falls back to the browser Canvas path; in a headless CI script there's no browser to fall back to, so check GET /v1/health first and fail with a clear message.

Favicon Master's runner-builtin requires Pro. A free-tier dispatch returns HTTP 429 with { error: "tier_limit_exceeded", limit, upgrade_url }. Retrying in-browser won't help — the cap is real. Upgrade or run a different tool.

The tool has no schema options, so any options payload is ignored — there's no background, padding, or size selection to set. Pre-process the SVG instead (square the viewBox, bake a background rect) before dispatching.

Generation stretches a non-square SVG onto each square canvas. Bake an aspect-ratio fix into the pipeline: run svg-viewbox-fixer (or normalise the source) before the favicon step so committed icons aren't squashed.

The hosted API can't help, and a pure headless CI box without the JAD runner can't rasterise Canvas. Run the favicon step on a developer machine (or a CI agent with the runner installed), commit the generated files, and let CI consume them as static assets.

Canvas rasterisation won't reliably load remote fonts, so <text> can disappear in the rendered PNGs. Convert text to paths with svg-font-to-path as an earlier pipeline step so the favicon is self-contained.

The package and the SVG <link> use your source filename stem (e.g. brand.svg). If you want /favicon.svg in the markup, name the source favicon.svg or rewrite the link tag in your unpack step. The hash guard keys off the source file regardless.