react-webpify 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# react-webpify
+
+A zero-config CLI that converts every image asset in your React project to **WebP** and rewrites all references — `import` statements, JSX `src`, CSS `url(...)`, HTML, and JSON manifests.
+
+Run once at the root of any React app (CRA, Vite, Next, etc.) and ship smaller images instantly.
+
+```bash
+npx react-webpify
+```
+
+## What it does
+
+1. **Scans** your project (`src/`, `public/`, `assets/`, `static/` by default) for `.png`, `.jpg`, `.jpeg`, and static `.gif` files.
+2. **Converts** each to `.webp` using [`sharp`](https://github.com/lovell/sharp).
+3. **Rewrites** every reference in your code — across `.js / .jsx / .ts / .tsx / .css / .scss / .less / .html / .json` — to point at the new `.webp`.
+4. **Deletes** the originals (override with `--keep-original`).
+5. Prints a summary with bytes saved.
+
+It works on every common ref shape: relative imports, root-absolute paths (`/logo.png`), CSS `url(...)`, HTML attributes, and JSON manifest entries. References are only modified inside string/URL contexts, so identifiers, comments, and unrelated substrings are never touched.
+
+## Install / Run
+
+```bash
+# one-shot, no install
+npx react-webpify
+
+# or add as a project script
+npm i -D react-webpify
+```
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "webpify": "react-webpify"
+  }
+}
+```
+
+## Options
+
+```
+npx react-webpify [options]
+
+  --dry-run              show what would change, write nothing
+  --keep-original        don't delete source images after conversion
+  --quality <n>          webp quality, 1-100 (default: 80)
+  --include <globs...>   extra dirs/globs to scan (default: src, public, assets, static)
+  --ignore <globs...>    additional paths to skip
+  --force                overwrite existing .webp files of the same basename
+  --no-update-refs       convert images only, leave code untouched
+  --verbose              print per-file logs
+  --cwd <path>           project root (default: current working directory)
+```
+
+Try a dry run first:
+
+```bash
+npx react-webpify --dry-run --verbose
+```
+
+## Caveats
+
+- **Dynamic refs**: paths built at runtime (e.g. `` `${base}/${name}.png` `` or `name + '.png'`) cannot be rewritten safely. The tool detects these and prints them as warnings so you can fix manually.
+- **Animated GIFs**: skipped by default — animated WebP is supported by `sharp` but lossy/risky enough that we leave them alone.
+- **Path aliases**: bundler aliases like `@/` are resolved heuristically (we try common forms). If you use a custom alias, double-check the resulting diff or run `--dry-run` first.
+- **Idempotent**: running twice is a no-op. Safe to wire into CI.
+
+## License
+
+MIT

package/bin/react-webpify.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv).catch((err) => {
+  console.error(err?.stack || err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "react-webpify",
+  "version": "0.1.0",
+  "description": "Convert all image assets in a React project to WebP and rewrite every code/CSS/HTML/JSON reference automatically.",
+  "type": "module",
+  "bin": {
+    "react-webpify": "./bin/react-webpify.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "react",
+    "webp",
+    "image",
+    "optimization",
+    "cli",
+    "performance"
+  ],
+  "author": {
+    "name": "mizanxali",
+    "email": "mizanalip786@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mizanxali/react-webpify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mizanxali/react-webpify/issues"
+  },
+  "homepage": "https://github.com/mizanxali/react-webpify#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "ora": "^8.1.0",
+    "sharp": "^0.33.5"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import path from 'node:path';
+import { webpify } from './index.js';
+
+export async function run(argv) {
+  const program = new Command();
+
+  program
+    .name('react-webpify')
+    .description(
+      'Convert every image asset in a React project to .webp and rewrite all references in JS/TS/CSS/HTML/JSON.'
+    )
+    .version('0.1.0')
+    .option('--dry-run', 'show what would change, write nothing', false)
+    .option('--keep-original', "don't delete source images after conversion", false)
+    .option('--quality <n>', 'webp quality (1-100)', (v) => parseInt(v, 10), 80)
+    .option(
+      '--include <globs...>',
+      'directories/globs to scan (default: src, public, assets, static)'
+    )
+    .option('--ignore <globs...>', 'additional paths to skip')
+    .option('--force', 'overwrite existing .webp files of the same basename', false)
+    .option('--no-update-refs', 'convert images only, do not rewrite code refs')
+    .option('--verbose', 'print per-file logs', false)
+    .option('--cwd <path>', 'project root (default: current working directory)');
+
+  program.parse(argv);
+  const opts = program.opts();
+
+  const cwd = path.resolve(opts.cwd || process.cwd());
+
+  await webpify({
+    cwd,
+    dryRun: !!opts.dryRun,
+    keepOriginal: !!opts.keepOriginal,
+    quality: clampQuality(opts.quality),
+    include: opts.include,
+    ignore: opts.ignore,
+    force: !!opts.force,
+    updateRefs: opts.updateRefs !== false,
+    verbose: !!opts.verbose,
+  });
+}
+
+function clampQuality(q) {
+  if (!Number.isFinite(q)) return 80;
+  return Math.max(1, Math.min(100, q));
+}

package/src/converter.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import sharp from 'sharp';
+import { isAnimatedGif } from './gif.js';
+
+export async function convertAll({ imageFiles, quality, force, dryRun, verbose, logger }) {
+  const mapping = new Map(); // oldAbsPath -> newAbsPath
+  const skippedAnimatedGifs = [];
+  let bytesBefore = 0;
+  let bytesAfter = 0;
+  let failed = 0;
+
+  for (const input of imageFiles) {
+    const ext = path.extname(input).toLowerCase();
+    const output = input.slice(0, -ext.length) + '.webp';
+
+    if (ext === '.gif' && (await isAnimatedGif(input))) {
+      skippedAnimatedGifs.push(input);
+      logger?.verbose(`skip animated gif: ${input}`);
+      continue;
+    }
+
+    if (!force) {
+      const exists = await pathExists(output);
+      if (exists) {
+        logger?.verbose(`exists, skipping: ${output}`);
+        continue;
+      }
+    }
+
+    try {
+      const beforeStat = await fs.stat(input);
+      bytesBefore += beforeStat.size;
+
+      if (!dryRun) {
+        await sharp(input, { animated: false }).webp({ quality }).toFile(output);
+        const afterStat = await fs.stat(output);
+        bytesAfter += afterStat.size;
+      } else {
+        // For dry-run we can't know the post-conversion size; just count input size.
+        bytesAfter += beforeStat.size;
+      }
+
+      mapping.set(input, output);
+      logger?.verbose(`converted: ${input} -> ${output}`);
+    } catch (err) {
+      failed++;
+      logger?.warn(`failed to convert ${input}: ${err.message}`);
+    }
+  }
+
+  return { mapping, skippedAnimatedGifs, bytesBefore, bytesAfter, failed };
+}
+
+export async function deleteOriginals(mapping, { dryRun, logger }) {
+  let deleted = 0;
+  for (const oldPath of mapping.keys()) {
+    try {
+      if (!dryRun) await fs.unlink(oldPath);
+      deleted++;
+      logger?.verbose(`deleted original: ${oldPath}`);
+    } catch (err) {
+      logger?.warn(`failed to delete ${oldPath}: ${err.message}`);
+    }
+  }
+  return deleted;
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/gif.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs/promises';
+
+// A GIF is animated when it contains more than one image descriptor (0x2C).
+// We walk the file byte-by-byte, respecting GIF block structure, and stop
+// as soon as we've counted a second frame.
+export async function isAnimatedGif(filePath) {
+  let buf;
+  try {
+    buf = await fs.readFile(filePath);
+  } catch {
+    return false;
+  }
+
+  // GIF89a / GIF87a header is 6 bytes; logical screen descriptor is 7 bytes.
+  if (buf.length < 13) return false;
+  if (buf.toString('ascii', 0, 3) !== 'GIF') return false;
+
+  let i = 13;
+  // Skip global color table if present.
+  const packed = buf[10];
+  if (packed & 0x80) {
+    const gctSize = 3 * (1 << ((packed & 0x07) + 1));
+    i += gctSize;
+  }
+
+  let frames = 0;
+
+  while (i < buf.length) {
+    const b = buf[i];
+
+    if (b === 0x3b) {
+      // Trailer.
+      break;
+    }
+
+    if (b === 0x21) {
+      // Extension block: 0x21, label, then sub-blocks until 0x00.
+      i += 2;
+      i = skipSubBlocks(buf, i);
+      continue;
+    }
+
+    if (b === 0x2c) {
+      frames++;
+      if (frames > 1) return true;
+
+      // Image descriptor: 9 bytes after the 0x2C separator.
+      i += 1 + 9;
+      const imgPacked = buf[i - 1];
+      if (imgPacked & 0x80) {
+        const lctSize = 3 * (1 << ((imgPacked & 0x07) + 1));
+        i += lctSize;
+      }
+      // LZW minimum code size byte.
+      i += 1;
+      i = skipSubBlocks(buf, i);
+      continue;
+    }
+
+    // Unknown byte — abort to avoid infinite loop.
+    break;
+  }
+
+  return false;
+}
+
+function skipSubBlocks(buf, i) {
+  while (i < buf.length) {
+    const size = buf[i++];
+    if (size === 0) break;
+    i += size;
+  }
+  return i;
+}

package/src/index.js

@@ -0,0 +1,113 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { scan } from './scanner.js';
+import { convertAll, deleteOriginals } from './converter.js';
+import { rewriteAll } from './rewriter.js';
+import { createLogger, formatBytes } from './logger.js';
+
+export async function webpify(options) {
+  const {
+    cwd,
+    dryRun = false,
+    keepOriginal = false,
+    quality = 80,
+    include,
+    ignore,
+    force = false,
+    updateRefs = true,
+    verbose = false,
+  } = options;
+
+  const logger = createLogger({ verbose });
+
+  if (dryRun) {
+    logger.info(chalk.cyan('Dry run — no files will be written.'));
+  }
+
+  const scanSpin = ora('Scanning project…').start();
+  const { imageFiles, codeFiles } = await scan({ cwd, include, ignore });
+  scanSpin.succeed(
+    `Found ${chalk.bold(imageFiles.length)} image(s), ${chalk.bold(codeFiles.length)} code file(s).`
+  );
+
+  if (imageFiles.length === 0) {
+    logger.info(chalk.gray('Nothing to convert.'));
+    return { converted: 0, filesUpdated: 0 };
+  }
+
+  const convSpin = ora('Converting to WebP…').start();
+  const { mapping, skippedAnimatedGifs, bytesBefore, bytesAfter, failed } = await convertAll({
+    imageFiles,
+    quality,
+    force,
+    dryRun,
+    verbose,
+    logger,
+  });
+  convSpin.succeed(`Converted ${chalk.bold(mapping.size)} image(s).`);
+
+  let filesUpdated = 0;
+  let dynamicWarnings = [];
+  if (updateRefs && mapping.size > 0) {
+    const refSpin = ora('Updating code references…').start();
+    const result = await rewriteAll({
+      codeFiles,
+      mapping,
+      cwd,
+      dryRun,
+      verbose,
+      logger,
+    });
+    filesUpdated = result.filesUpdated;
+    dynamicWarnings = result.dynamicWarnings;
+    refSpin.succeed(`Updated refs in ${chalk.bold(filesUpdated)} file(s).`);
+  }
+
+  let deleted = 0;
+  if (!keepOriginal && mapping.size > 0) {
+    const delSpin = ora('Removing originals…').start();
+    deleted = await deleteOriginals(mapping, { dryRun, logger });
+    delSpin.succeed(`Removed ${chalk.bold(deleted)} original file(s).`);
+  }
+
+  // Summary
+  const savedBytes = Math.max(0, bytesBefore - bytesAfter);
+  console.log('');
+  console.log(chalk.bold('Summary'));
+  console.log(`  Converted:        ${mapping.size}`);
+  if (failed) console.log(`  Failed:           ${chalk.red(failed)}`);
+  if (skippedAnimatedGifs.length)
+    console.log(`  Skipped (gif):    ${skippedAnimatedGifs.length} animated`);
+  console.log(`  Refs updated in:  ${filesUpdated} file(s)`);
+  if (!keepOriginal) console.log(`  Originals removed: ${deleted}`);
+  console.log(
+    `  Bytes saved:      ${chalk.green(formatBytes(savedBytes))} ` +
+      chalk.gray(`(${formatBytes(bytesBefore)} → ${formatBytes(bytesAfter)})`)
+  );
+
+  if (dynamicWarnings.length) {
+    console.log('');
+    console.log(chalk.yellow.bold(`! ${dynamicWarnings.length} dynamic image ref(s) need manual review:`));
+    for (const w of dynamicWarnings.slice(0, 10)) {
+      console.log(chalk.yellow(`  ${w.file}: ${w.match}  (${w.reason})`));
+    }
+    if (dynamicWarnings.length > 10) {
+      console.log(chalk.yellow(`  …and ${dynamicWarnings.length - 10} more`));
+    }
+  }
+
+  if (dryRun) {
+    console.log('');
+    console.log(chalk.cyan('Dry run complete. Re-run without --dry-run to apply.'));
+  }
+
+  return {
+    converted: mapping.size,
+    filesUpdated,
+    skippedAnimatedGifs: skippedAnimatedGifs.length,
+    bytesBefore,
+    bytesAfter,
+    failed,
+    dynamicWarnings,
+  };
+}

package/src/logger.js

@@ -0,0 +1,24 @@
+import chalk from 'chalk';
+
+export function createLogger({ verbose }) {
+  return {
+    info: (msg) => console.log(msg),
+    verbose: (msg) => {
+      if (verbose) console.log(chalk.gray('  ' + msg));
+    },
+    warn: (msg) => console.warn(chalk.yellow('! ' + msg)),
+    error: (msg) => console.error(chalk.red('✖ ' + msg)),
+  };
+}
+
+export function formatBytes(n) {
+  if (!Number.isFinite(n) || n <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let i = 0;
+  let v = n;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(v >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+}

package/src/scanner.js

@@ -0,0 +1,52 @@
+import fg from 'fast-glob';
+import path from 'node:path';
+
+const DEFAULT_INCLUDE = ['src', 'public', 'assets', 'static', 'app', 'pages', 'components'];
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.git/**',
+  '**/.next/**',
+  '**/.turbo/**',
+  '**/.cache/**',
+  '**/coverage/**',
+  '**/out/**',
+];
+
+const IMAGE_EXTS = ['png', 'jpg', 'jpeg', 'gif'];
+const CODE_EXTS = ['js', 'jsx', 'ts', 'tsx', 'mjs', 'cjs', 'css', 'scss', 'sass', 'less', 'html', 'htm', 'json'];
+
+export async function scan({ cwd, include, ignore }) {
+  const roots = include && include.length ? include : DEFAULT_INCLUDE;
+  const ignoreList = [...DEFAULT_IGNORE, ...(ignore || [])];
+
+  const existingRoots = await filterExistingRoots(cwd, roots);
+  const searchRoots = existingRoots.length ? existingRoots : ['.'];
+
+  const imageGlobs = searchRoots.map((r) => `${r}/**/*.{${IMAGE_EXTS.join(',')}}`);
+  const codeGlobs = searchRoots.map((r) => `${r}/**/*.{${CODE_EXTS.join(',')}}`);
+
+  const [imageFiles, codeFiles] = await Promise.all([
+    fg(imageGlobs, { cwd, ignore: ignoreList, absolute: true, caseSensitiveMatch: false, dot: false }),
+    fg(codeGlobs, { cwd, ignore: ignoreList, absolute: true, caseSensitiveMatch: false, dot: false }),
+  ]);
+
+  return { imageFiles, codeFiles };
+}
+
+async function filterExistingRoots(cwd, roots) {
+  const fs = await import('node:fs/promises');
+  const out = [];
+  for (const r of roots) {
+    try {
+      const stat = await fs.stat(path.join(cwd, r));
+      if (stat.isDirectory()) out.push(r);
+    } catch {
+      // skip missing dir
+    }
+  }
+  return out;
+}
+
+export const __test = { DEFAULT_INCLUDE, DEFAULT_IGNORE, IMAGE_EXTS, CODE_EXTS };