convert-svg-to-webp-cli

convert-svg-to-webp-cli

A Node.js package for converting SVG to WEBP using headless Chromium via CLI.

If you want to convert SVG to WEBP programmatically, you should instead look at convert-svg-to-webp.

Install

Install using npm to access the convert-svg-to-webp command from anywhere:

npm install --global convert-svg-to-webp-cli

You'll need to have at least Node.js v22 or newer.

This package uses Puppeteer under-the-hood to interface with a headless Chromium instance and will download and install a headless Chromium instance for you.

Usage

Usage: convert-svg-to-webp [options] [files...]


  Options:

    -V, --version          output the version number
    --no-color             disables color output
    --background <color>   specify background color for transparent regions in SVG
    --base-url <url>       specify base URL to use for all relative URLs in SVG
    --filename <filename>  specify filename for the WEBP output when processing STDIN
    --height <value>       specify height for WEBP
    --launch <json>        specify a json object passed to puppeteer when launching a browser
    --page <json>          specify a json object passed to puppeteer opening a page
    --rounding <type>      specify type of rounding to apply to dimensions
    --scale <value>        specify scale to apply to dimensions [1]
    --width <value>        specify width for WEBP
    --quality <value>      specify quality for WEBP [100]
    -h, --help             output usage information

The CLI can be used in the following ways:

• Pass SVG files to be converted to WEBP files as command arguments
  • A glob pattern can be passed
  • Each converted SVG file will result in a corresponding WEBP with the same base file name (e.g. image.svg -> image.webp)
• Pipe SVG buffer to be converted to WEBP to command via STDIN
  • If the --filename option is passed, the WEBP will be written to a file resolved using its value
  • Otherwise, the WEBP will be streamed to STDOUT

Environment

This package supports the use of a CONVERT_SVG_LAUNCH_OPTIONS environment variable to act as a base for the --launch option. This can make it easier to control the browser launch/connection. For example;

export CONVERT_SVG_LAUNCH_OPTIONS='{"browser": "firefox", "executablePath": "/Applications/Firefox.app/Contents/MacOS/firefox"}'

macOS

⚠️ Heads up!

If you are using this package on macOS it's important to note that there is a noticeable reduction in the quality of output files compared to other operating systems. This appears to be caused by SVG rendering within Chromium on macOS itself.

As such, there are a few options available:

• Connect this package to a Firefox instance; however, some features may not be supported due to their lack of > support in WebDriver BiDi.
• Run this package on Linux (e.g. Ubuntu), even if it's just within Docker, will have noticeable improvements of > macOS rendering.
• If possible, increase the size of the input SVG as this can sometimes result in a better output.

Other Formats

If you would like to convert an SVG into a format other than WEBP, check out our other converter packages below:

https://github.com/neocotic/convert-svg

Bugs

If you have any problems with this package or would like to see changes currently in development, you can do so here.

Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in CONTRIBUTING.md. We want your suggestions and pull requests!

A list of all contributors can be found in AUTHORS.md.

License

Copyright © 2025 neocotic

See LICENSE.md for more information on our MIT license.

Changelog

Version 0.7.1, 2025.06.17

• Allow import('puppeteer').executablePath to be passed directly in launch options to allow other launch options to be passed to it as a function
• Document supported CONVERT_SVG_* environment variables
• Document potential issues with reduced quality on macOS
• Add Docker support for running the test suite on a Linux-based image
• Bump all dependencies to latest versions