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.

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.
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

# one-shot, no install
npx react-webpify

# or add as a project script
npm i -D react-webpify

package.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:

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