Batch-Purge Unused SVG Definitions with the JAD Desktop Runner

Loop the desktop runner over an icons folder

Drive the runner one file at a time. The loop is your batch; each job carries a single file and an empty options object.

# pseudo-driver against the local JAD runner
for f in ./src/icons/*.svg; do
  jad-runner run svg-unused-defs-purger \
    --file "$f" \
    --out "./dist/icons/$(basename "${f%.svg}")-purged.svg"
done

# Each run prints: Defs removed: N  (original → output bytes)
# No --preserve / --options flags exist for this tool.

Two-pass purge to clear transitive orphans

A second pass collects defs that only became dead after the first removed their sole referrer (the def-to-def cascade).

purge ./icon.svg        → icon-purged.svg     (Defs removed: 2)
purge ./icon-purged.svg → icon-purged-purged.svg (Defs removed: 1)

# Pass 1 removed a clipPath; the gradient it referenced
# became orphaned and is swept up only on pass 2.

Purge → minify → tune precision pipeline

Chain three SVG tools so each does its one job. Purge first so the minifier has less markup to process.

stage 1  svg-unused-defs-purger  (drop dead <defs>)
stage 2  svg-pro-minifier        (strip comments/whitespace)
stage 3  svg-precision-tuner     (round coords to 2 dp)

# Order matters: removing defs before minifying means the
# minifier never touches markup that's about to be deleted.

Pre-commit guard on staged SVGs

Run the purger only on SVGs staged for commit so dead defs never enter history. Drive the runner per staged file.

# .git/hooks/pre-commit (sketch)
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.svg$')
for f in $files; do
  jad-runner run svg-unused-defs-purger --file "$f" --inplace
  git add "$f"
done
# Commit proceeds with purged SVGs.

Gate the pipeline on a visual diff

Because external-CSS / JS-referenced ids can be false-positived away, fail the build if any icon changes pixels after purging.

purge all icons → render each to PNG → diff vs baseline

if any diff > 0 px:
  FAIL — a 'dead' def was actually referenced
         (likely from external CSS or JS).
  → exclude that file from the purge set, or inline the ref.
else:
  PASS — defs removal was safe.

There is no cloud endpoint. The engine throws "svg-unused-defs-purger is not exposed via the API — it requires browser-side processing (DOM, Canvas, or remote-font fetch). Use the web tool." Automate via the desktop runner or the browser tool instead.

The tool defines no options. Any preserve_ids, purge_unused_defs, or similar field in the options object is ignored — removal is fully automatic. To protect a def with no static reference, keep that file out of the purge set.

This is a single-file operation. There is no server-side batch array — you loop and dispatch one job per file. Only the sprite builder is multi-file among the SVG tools.

The purger requires Pro both in the browser (upgrade overlay otherwise) and in the runner (tierRequired: pro). Free-tier jobs are not dispatched to the runner at all — runner acceleration is a paid perk — so they would also fail the browser gate. Use a Pro plan.

If a component stylesheet applies filter: url(#fx) from outside the SVG, the purger removes fx as unused. The visual-regression gate is your safety net — diff the rendered icon and exclude any file that changes.

If the runner errors, the web client logs a warning and falls back to the in-browser path so the user still gets a result. In a headless driver, handle the fallback explicitly: if the runner call fails, process that file in the browser tool or retry.

SVGs that embed PNG/JPEG as base64 can exceed the 50 MB Pro ceiling and are rejected before processing. The purger does not touch raster payloads anyway — strip or externalise the embedded image first; estimate the weight with the SVG Compression Estimator.

A single pass keeps defs referenced only inside a doomed def. Pipelines that want a fully minimal <defs> should run the purger twice (or until Defs removed reaches 0). Loop until the metric stabilises.