@marcovega/svg-tidy 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Vega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# svg-tidy
+
+[![npm version](https://img.shields.io/npm/v/@marcovega/svg-tidy.svg)](https://www.npmjs.com/package/@marcovega/svg-tidy)
+
+A tiny CLI that optimizes every `.svg` file in a directory using
+[SVGO](https://github.com/svg/svgo) with the same plugin settings as the
+[SVGOMG](https://svgomg.net/) preset.
+
+On the **first** run inside a directory it writes a `.svgtidy.json` file with
+the default plugin settings. On subsequent runs it reads that file. Commit it
+to your repo so everyone on the team optimizes icons the same way.
+
+It rewrites each `.svg` file **in place**, so the result is ready to drop into
+your assets folder.
+
+## Quick start
+
+No install needed — just run it with `npx`:
+
+```bash
+cd path/to/your/svgs
+npx @marcovega/svg-tidy
+```
+
+Or install globally (the binary is `svg-tidy`):
+
+```bash
+npm install -g @marcovega/svg-tidy
+svg-tidy
+```
+
+## Usage
+
+```text
+svg-tidy [paths...] [options]
+
+Arguments:
+  paths              Files or directories to process. Defaults to the current
+                     working directory.
+
+Options:
+  -r, --recursive    Recurse into subdirectories when a directory is given.
+  -n, --dry-run      Show what would change without writing files.
+  -q, --quiet        Only print the final summary.
+      --init         Write a default .svgtidy.json (if missing) and exit.
+      --config PATH  Use a specific config file. Defaults to ./.svgtidy.json.
+  -h, --help         Show this help.
+```
+
+Examples:
+
+```bash
+npx @marcovega/svg-tidy                  # optimize every .svg in this dir
+npx @marcovega/svg-tidy -r                # ...recursively
+npx @marcovega/svg-tidy ./icons logo.svg  # specific paths
+npx @marcovega/svg-tidy -n                # preview savings, don't write
+npx @marcovega/svg-tidy --init            # just create .svgtidy.json and stop
+```
+
+Each file is overwritten only when SVGO actually changes its contents.
+
+## The `.svgtidy.json` config file
+
+The first time you run `svg-tidy` in a directory it creates
+`.svgtidy.json` next to your icons. The file uses the SVGOMG-style boolean
+plugin map:
+
+```json
+{
+  "multipass": true,
+  "js2svg": { "indent": 2, "pretty": false },
+  "plugins": {
+    "cleanupAttrs": true,
+    "cleanupIDs": true,
+    "cleanupListOfValues": false,
+    "removeViewBox": false,
+    "removeXMLNS": false,
+    "removeScriptElement": false,
+    "removeStyleElement": false
+  }
+}
+```
+
+To customize: edit the file, set a plugin to `false` to disable it, or pass
+custom plugin params with an object value:
+
+```json
+{
+  "plugins": {
+    "removeDesc": { "removeAny": true },
+    "cleanupIds": { "minify": false }
+  }
+}
+```
+
+Commit `.svgtidy.json` to your repo so collaborators (and CI) get the same
+optimizations every time someone runs `svg-tidy`.
+
+### Notes on renamed SVGO plugins
+
+SVGO renamed a couple plugins between the SVGOMG UI and modern SVGO. Both
+old and new names are accepted in `.svgtidy.json`:
+
+| SVGOMG name           | SVGO v4 name      |
+| --------------------- | ----------------- |
+| `cleanupIDs`          | `cleanupIds`      |
+| `removeScriptElement` | `removeScripts`   |
+
+## How `npx` finds this package
+
+`npx some-package` does one of three things, in order:
+
+1. Runs `some-package` from the current project's `node_modules/.bin/`.
+2. Runs it from your global `PATH`.
+3. Downloads it from the npm registry to a temp cache and runs it.
+
+Because `@marcovega/svg-tidy` is published to npm, option 3 just works — no
+`npm link` required for end users.
+
+## Local development
+
+```bash
+git clone git@github.com:marcovega/svg-tidy.git
+cd svg-tidy
+npm install
+npm link            # makes `svg-tidy` available globally for testing
+```
+
+To remove the global symlink later: `npm unlink -g @marcovega/svg-tidy`.
+
+## Updating SVGO
+
+```bash
+npm install svgo@latest
+```
+
+## License
+
+[MIT](./LICENSE)

package/bin/svg-tidy.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import process from 'node:process';
+import { optimize } from 'svgo';
+import {
+  CONFIG_FILENAME,
+  loadOrCreateConfig,
+  resolveConfigPath,
+  toSvgoOptions,
+} from '../lib/config.js';
+
+const HELP = `svg-tidy - optimize SVG files in place using SVGO
+
+Usage:
+  svg-tidy [paths...] [options]
+
+Arguments:
+  paths              Files or directories to process. Defaults to the current
+                     working directory.
+
+Options:
+  -r, --recursive    Recurse into subdirectories when a directory is given.
+  -n, --dry-run      Show what would change without writing files.
+  -q, --quiet        Only print the final summary.
+      --init         Write a default ${CONFIG_FILENAME} (if missing) and exit.
+      --config PATH  Use a specific config file. Defaults to ./${CONFIG_FILENAME}.
+  -h, --help         Show this help.
+
+Config:
+  On first run in a directory svg-tidy writes ${CONFIG_FILENAME} with the
+  SVGOMG-style default plugin settings. Edit that file (or commit it) to
+  customize how SVGs are optimized. Subsequent runs reuse it.
+
+Examples:
+  svg-tidy                       # optimize every .svg in this dir
+  svg-tidy -r                    # ...recursively
+  svg-tidy ./icons logo.svg      # specific paths
+  svg-tidy -n                    # preview savings, don't write
+  svg-tidy --init                # just create the default config and stop
+`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    recursive: { type: 'boolean', short: 'r', default: false },
+    'dry-run': { type: 'boolean', short: 'n', default: false },
+    quiet: { type: 'boolean', short: 'q', default: false },
+    init: { type: 'boolean', default: false },
+    config: { type: 'string' },
+    help: { type: 'boolean', short: 'h', default: false },
+  },
+});
+
+if (values.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+const recursive = values.recursive;
+const dryRun = values['dry-run'];
+const quiet = values.quiet;
+const initOnly = values.init;
+const targets = positionals.length > 0 ? positionals : [process.cwd()];
+
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function pct(before, after) {
+  if (before === 0) return '0.0%';
+  return `${(((before - after) / before) * 100).toFixed(1)}%`;
+}
+
+async function collectSvgs(target) {
+  const resolved = path.resolve(target);
+  let entryStat;
+  try {
+    entryStat = await stat(resolved);
+  } catch (err) {
+    throw new Error(`Cannot access ${target}: ${err.message}`);
+  }
+
+  if (entryStat.isFile()) {
+    return resolved.toLowerCase().endsWith('.svg') ? [resolved] : [];
+  }
+
+  if (!entryStat.isDirectory()) return [];
+
+  const files = [];
+  const entries = await readdir(resolved, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(resolved, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) files.push(...(await collectSvgs(full)));
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.svg')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+async function processFile(file, svgoOptions) {
+  const original = await readFile(file, 'utf8');
+  const result = optimize(original, { path: file, ...svgoOptions });
+
+  if (result.error) throw new Error(result.error);
+
+  const optimized = result.data;
+  const beforeBytes = Buffer.byteLength(original, 'utf8');
+  const afterBytes = Buffer.byteLength(optimized, 'utf8');
+  const changed = optimized !== original;
+
+  if (changed && !dryRun) {
+    await writeFile(file, optimized, 'utf8');
+  }
+
+  return { file, beforeBytes, afterBytes, changed };
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const configPath = resolveConfigPath(cwd, values.config);
+
+  const { config, created } = await loadOrCreateConfig(configPath);
+  const svgoOptions = toSvgoOptions(config);
+  const relConfig = path.relative(cwd, configPath) || configPath;
+
+  if (created) {
+    console.log(`Wrote default config to ${relConfig}.`);
+    console.log('Edit it to customize plugins, then re-run svg-tidy.');
+  } else if (!quiet) {
+    console.log(`Using config: ${relConfig}`);
+  }
+
+  if (initOnly) {
+    if (!created) console.log(`${relConfig} already exists. No changes made.`);
+    return;
+  }
+
+  const allFiles = new Set();
+  for (const target of targets) {
+    const found = await collectSvgs(target);
+    for (const f of found) allFiles.add(f);
+  }
+  const files = [...allFiles].sort();
+
+  if (files.length === 0) {
+    console.error('No .svg files found.');
+    process.exit(1);
+  }
+
+  let totalBefore = 0;
+  let totalAfter = 0;
+  let changedCount = 0;
+  let failedCount = 0;
+
+  for (const file of files) {
+    try {
+      const r = await processFile(file, svgoOptions);
+      totalBefore += r.beforeBytes;
+      totalAfter += r.afterBytes;
+      if (r.changed) changedCount += 1;
+      if (!quiet) {
+        const rel = path.relative(cwd, r.file) || r.file;
+        const tag = r.changed
+          ? `${formatBytes(r.beforeBytes)} -> ${formatBytes(r.afterBytes)} (${pct(r.beforeBytes, r.afterBytes)})`
+          : 'no change';
+        console.log(`${dryRun && r.changed ? '[dry] ' : ''}${rel}: ${tag}`);
+      }
+    } catch (err) {
+      failedCount += 1;
+      console.error(`FAILED ${file}: ${err.message}`);
+    }
+  }
+
+  const verb = dryRun ? 'Would optimize' : 'Optimized';
+  console.log(
+    `\n${verb} ${changedCount}/${files.length} file(s). ` +
+      `Total: ${formatBytes(totalBefore)} -> ${formatBytes(totalAfter)} ` +
+      `(${pct(totalBefore, totalAfter)} smaller)` +
+      (failedCount ? `. ${failedCount} failed.` : '.'),
+  );
+
+  if (failedCount > 0) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.stack || err.message || err);
+  process.exit(1);
+});

package/lib/config.js

@@ -0,0 +1,87 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_CONFIG, PLUGIN_ALIASES } from './svgo-config.js';
+
+export const CONFIG_FILENAME = '.svgtidy.json';
+
+/**
+ * Resolve where the config file lives.
+ *
+ * - If `configPath` is provided, use it verbatim.
+ * - Otherwise look in `cwd` for `.svgtidy.json`.
+ */
+export function resolveConfigPath(cwd, configPath) {
+  if (configPath) return path.resolve(cwd, configPath);
+  return path.join(cwd, CONFIG_FILENAME);
+}
+
+/**
+ * Load `.svgtidy.json` from disk. If it doesn't exist, write the default config
+ * to that path first.
+ *
+ * Returns `{ config, path, created }`.
+ */
+export async function loadOrCreateConfig(configPath) {
+  let raw;
+  let created = false;
+  try {
+    raw = await readFile(configPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    raw = JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n';
+    await writeFile(configPath, raw, 'utf8');
+    created = true;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
+  }
+
+  return { config: parsed, path: configPath, created };
+}
+
+/**
+ * Convert a svg-tidy config (with a boolean/params plugin map) into the
+ * options object expected by SVGO's `optimize()` function.
+ */
+export function toSvgoOptions(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Config must be an object.');
+  }
+
+  const { multipass, js2svg, plugins: pluginMap } = config;
+
+  if (pluginMap && typeof pluginMap !== 'object') {
+    throw new Error('Config "plugins" must be an object map of name -> bool|params.');
+  }
+
+  const seen = new Set();
+  const plugins = [];
+
+  for (const [rawName, value] of Object.entries(pluginMap || {})) {
+    if (value === false || value == null) continue;
+
+    const name = PLUGIN_ALIASES[rawName] || rawName;
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    if (value === true) {
+      plugins.push(name);
+    } else if (typeof value === 'object') {
+      plugins.push({ name, params: value });
+    } else {
+      throw new Error(
+        `Config plugin "${rawName}" must be a boolean or an object, got ${typeof value}.`,
+      );
+    }
+  }
+
+  return {
+    multipass: Boolean(multipass),
+    js2svg: js2svg || undefined,
+    plugins,
+  };
+}

package/lib/svgo-config.js

@@ -0,0 +1,73 @@
+/**
+ * Default SVGO plugin configuration for svg-tidy.
+ *
+ * `DEFAULT_CONFIG.plugins` is a SVGOMG-style boolean map (the same shape used
+ * in the amazing-facts theme docs). Each key is a plugin name, the value is:
+ *   - `true`               -> enable the plugin with its default params
+ *   - `false`              -> disable it (omitted from SVGO's plugin list)
+ *   - an `object` (params) -> enable with custom params
+ *
+ * The persisted `.svgtidy.json` file uses this exact shape so it's easy to
+ * read, edit, and diff.
+ *
+ * SVGO renamed two plugins between the SVGOMG UI and modern SVGO; both old and
+ * new names are accepted in the config file and normalized via PLUGIN_ALIASES.
+ */
+
+export const PLUGIN_ALIASES = {
+  cleanupIDs: 'cleanupIds',
+  removeScriptElement: 'removeScripts',
+};
+
+export const DEFAULT_CONFIG = {
+  multipass: true,
+  js2svg: {
+    indent: 2,
+    pretty: false,
+  },
+  plugins: {
+    cleanupAttrs: true,
+    cleanupEnableBackground: true,
+    cleanupIDs: true,
+    cleanupListOfValues: false,
+    cleanupNumericValues: true,
+    collapseGroups: true,
+    convertColors: true,
+    convertEllipseToCircle: true,
+    convertPathData: true,
+    convertShapeToPath: true,
+    convertStyleToAttrs: true,
+    convertTransform: true,
+    inlineStyles: true,
+    mergePaths: true,
+    mergeStyles: true,
+    minifyStyles: true,
+    moveElemsAttrsToGroup: true,
+    moveGroupAttrsToElems: true,
+    removeComments: true,
+    removeDesc: true,
+    removeDimensions: true,
+    removeDoctype: true,
+    removeEditorsNSData: true,
+    removeEmptyAttrs: true,
+    removeEmptyContainers: true,
+    removeEmptyText: true,
+    removeHiddenElems: true,
+    removeMetadata: true,
+    removeNonInheritableGroupAttrs: true,
+    removeRasterImages: true,
+    removeScriptElement: false,
+    removeStyleElement: false,
+    removeTitle: true,
+    removeUnknownsAndDefaults: true,
+    removeUnusedNS: true,
+    removeUselessDefs: true,
+    removeUselessStrokeAndFill: true,
+    removeViewBox: false,
+    removeXMLNS: false,
+    removeXMLProcInst: true,
+    reusePaths: false,
+    sortAttrs: false,
+    sortDefsChildren: true,
+  },
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@marcovega/svg-tidy",
+  "version": "0.2.0",
+  "description": "Optimize SVG icons in a directory using SVGO. Writes a .svgtidy.json config on first run so you can customize and commit settings per project.",
+  "type": "module",
+  "bin": {
+    "svg-tidy": "bin/svg-tidy.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "scripts": {
+    "start": "node bin/svg-tidy.js"
+  },
+  "dependencies": {
+    "svgo": "^4.0.1"
+  },
+  "keywords": [
+    "svg",
+    "svgo",
+    "svgomg",
+    "optimize",
+    "minify",
+    "icons",
+    "cli",
+    "npx"
+  ],
+  "author": "Marco Vega",
+  "license": "MIT",
+  "homepage": "https://github.com/marcovega/svg-tidy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcovega/svg-tidy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marcovega/svg-tidy/issues"
+  }
+}