Batch SVG ViewBox Standardization with Automation Scripts

Discover the schema (curl)

Before scripting, confirm the option shape and runner mode. This is the only call that touches JAD's cloud; no file content is sent.

curl -s https://jadapps.com/api/v1/tools/svg-viewbox-fixer \
  -H "Authorization: Bearer $JAD_API_KEY" | jq '.options, .execution'

# → options: [ { name:"addPadding", type:"number",
#               default:0, min:0, max:50, step:1 } ]
# → execution: { runnerMode:"headless-browser" }

Confirm the cloud /run is upload-free

Hitting the cloud run endpoint returns pairing instructions, never a result. This is by design — proof that file content is processed locally.

curl -s -X POST https://jadapps.com/api/v1/tools/svg-viewbox-fixer/run \
  -H "Authorization: Bearer $JAD_API_KEY" -d '{}'

# 400 {
#   "error": "Runner required",
#   "runnerEndpoint": "http://127.0.0.1:9789/v1/tools/svg-viewbox-fixer/run",
#   "schemaEndpoint": ".../api/v1/tools/svg-viewbox-fixer",
#   "installRunner": ".../docs/runner"
# }

Node: walk a folder and fix every icon

Reads each .svg in ./icons, POSTs to the local runner with a fixed padding, and writes the result next to the source. Logs any file that fell back to declared dimensions.

import fs from 'node:fs';
import path from 'node:path';

const DIR = './icons';
const RUNNER = 'http://127.0.0.1:9789/v1/tools/svg-viewbox-fixer/run';
const addPadding = 0; // 0..50

const files = fs.readdirSync(DIR).filter(f => f.endsWith('.svg'));
for (const f of files) {
  const svg = fs.readFileSync(path.join(DIR, f), 'utf8');
  const res = await fetch(RUNNER, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      slug: 'svg-viewbox-fixer',
      files: [{ name: f, content: svg }],
      options: { addPadding },
    }),
  });
  const out = await res.json();
  const stem = f.replace(/\.svg$/, '');
  fs.writeFileSync(path.join(DIR, `${stem}-viewbox-fixed.svg`), out.content);
  if (out.metrics?.['Computed bbox'] !== 'yes')
    console.warn(`fallback: ${f} → ${out.metrics?.['New viewBox']}`);
}
console.log(`Fixed ${files.length} icons`);

Audit-only: list files that lack a viewBox

Before mutating anything, find which icons actually need fixing. This is a local read — no runner or API needed.

import fs from 'node:fs';
for (const f of fs.readdirSync('./icons').filter(x => x.endsWith('.svg'))) {
  const s = fs.readFileSync(`./icons/${f}`, 'utf8');
  const hasVB = /viewBox="[^"]+"/.test(s);
  const hasPx = /\b(width|height)="[\d.]+(px)?"/.test(s);
  if (!hasVB) console.log(`NO VIEWBOX: ${f}`);
  else if (hasPx) console.log(`px dims (will be stripped): ${f}`);
}

Pre-commit hook idea

Run the fixer only on staged SVGs so new icons land with a correct viewBox. Skeleton — adapt the staged-file detection to your VCS.

# .git/hooks/pre-commit (excerpt)
staged=$(git diff --cached --name-only --diff-filter=ACM -- '*.svg')
[ -z "$staged" ] && exit 0
node scripts/fix-viewbox.mjs $staged   # POSTs each to localhost:9789
git add $staged                        # re-stage the fixed files

# Files are processed by your local runner; nothing is uploaded.

The cloud /run route never accepts uploads — it validates your key, checks rate limits, then returns a 400 with runnerEndpoint, schemaEndpoint and installRunner. Don't try to base64 your SVG into the cloud call; route file content to http://127.0.0.1:9789 instead. This is the privacy guarantee, not a bug.

If nothing is listening on 127.0.0.1:9789, your fetch to the runner throws ECONNREFUSED. Install and pair @jadapps/runner first (the cloud response's installRunner link points to the docs). Wrap runner calls in a try/catch and surface a clear 'start the runner' message in CI logs.

The API/runner validates numeric options against the schema. Sending addPadding: 80 fails with Option "addPadding" must be ≤ 50. The browser slider caps at 20 so it never trips this, but a script can — clamp your value to 0–50 before sending.

Passing addPadding: "large" or addPadding: null is rejected: a number-typed option that isn't finite throws must be a number. Omitting the field entirely is fine — the engine applies the default of 0. Send a real number or nothing.

SVG-family caps apply: 5 MB (free), 50 MB (Pro), 200 MB (Pro+Media), 2 GB (Developer). An oversized file is rejected. SVGs are text, so this almost always means embedded base64 rasters — which the viewBox computation can't measure anyway. Strip embedded images before processing.

Files whose only content is <text>, <image>, or empty defs return Computed bbox: no (fallback) and use declared viewBox/width/height (24×24 if absent). Your script should treat any non-yes flag as 'needs human review' rather than trusting the box blindly.

The box is computed from raw path numbers, so icons built from C/Q/A curves or lowercase relative commands can produce a box that's slightly too large or offset (control points and arc params are counted as coordinates). For a CI gate, accept these as safe over-estimates, or pre-normalize paths to absolute coordinates upstream.

The runner uses the same logic as the browser tool and ignores transform attributes. Icons that position content via group transforms will get a box that doesn't match the rendered result. Flatten transforms in a build step (or with your vector toolchain) before the viewBox pass.

The cloud schema/dispatch layer is rate-limited per key (X-RateLimit-* headers report the budget). Discovery is one call per tool — cache the schema and reuse it across your whole batch rather than re-fetching per file. The local runner calls are not subject to the cloud rate limit.

Writing the fixed SVG over the original loses the ability to diff. Commit to git first (or write to <stem>-viewbox-fixed.svg as the script above does), then review the diff — only the root <svg> attributes should change. Because the fixer strips px width/height, a noisy diff there is expected and correct.