convert-svg-to-webp

convert-svg-to-webp

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

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

Install

Install using npm:

npm install --save convert-svg-to-webp

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, however, this package does not* download and install a headless Chromium instance for you as of version v0.7.0. The easiest solution is to also install puppeteer and connect it:

npm install --save puppeteer

Continue reading for more information on how to connect puppeteer to convert-svg-to-webp.

Usage

convert(input, options)

Converts the specified input SVG into a WEBP using the options provided via a headless Chromium instance.

input can either be an SVG buffer or string.

If the width and/or height cannot be derived from input, then they must be provided via their corresponding options. This method attempts to derive the dimensions from input via any width/height attributes or its calculated viewBox attribute.

Only standard SVG element attributes (excl. event attributes) are allowed, and others are stripped from the SVG before being converted. This includes deprecated attributes unless the allowDeprecatedAttributes option is disabled. This is primarily for security purposes to ensure that malicious code cannot be injected.

This method is resolved with the WEBP output buffer.

An error will occur if both the baseFile and baseUrl options have been provided, input does not contain an SVG element or no width and/or height options were provided, and this information could not be derived from input.

A Converter is created and closed to perform this operation using a this createConverter function below. If multiple files are being converted it is recommended to use createConverter to create a Converter and call its Converter#convert method multiple times instead.

Options

Option	Type	Default	Description
allowDeprecatedAttributes	boolean	true	Whether deprecated SVG element attributes should be retained in the SVG during conversion.
background	string	"#FFF" (White)	Background color to be used to fill transparent regions within the SVG.
baseFile	string	process.cwd()	Path of the file to be converted into a file URL to use for all relative URLs contained within the SVG. Cannot be used in conjunction with the baseUrl option.
baseUrl	string	"file:///${process.cwd()}"	Base URL to use for all relative URLs contained within the SVG. Cannot be used in conjunction with the baseFile option.
browser	object	None	Existing Browser instance provided by puppeteer that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. If specified, the launch option will be ignored.
closeBehavior	"close" | "disconnect" | "none"	"close"	Behavior when the converter is closed.
height	number | string	Derived	Height of the output to be generated. Derived from SVG input if omitted.
quality	number	100	Quality of the output to be generated. Must be between 0-100 (inclusive).
launch	object	None	Options that are to be passed directly to puppeteer when launching a new Browser that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. Ignored if the browser option is also specified.
page	object	None	Options that are to be passed directly to puppeteer when populating a Page with the SVG contents.
rounding	"ceil" | "floor" | "round"	"round"	Type of rounding to be applied to the width and height.
scale	number	1	Scale to be applied to the width and height (specified as options or derived).
width	number | string	Derived	Width of the output to be generated. Derived from SVG input if omitted.

Examples

import { convert } from "convert-svg-to-webp";
import express from "express";
import { executablePath } from "puppeteer";

const app = express();

app.post("/convert", async (req, res) => {
  const webp = await convert(req.body, {
    launch: { executablePath },
  });

  res.set("Content-Type", "image/webp");
  res.send(webp);
});

app.listen(3000);

convertFile(inputFilePath, options)

Converts the SVG file at the specified path into a WEBP using the options provided and writes it to the output file.

The output file is derived from inputFilePath unless the outputFilePath option is specified.

If the width and/or height cannot be derived from the input file, then they must be provided via their corresponding options. This method attempts to derive the dimensions from the input file via any width/height attributes or its calculated viewBox attribute.

Only standard SVG element attributes (excl. event attributes) are allowed, and others are stripped from the SVG before being converted. This includes deprecated attributes unless the allowDeprecatedAttributes option is disabled. This is primarily for security purposes to ensure that malicious code cannot be injected.

This method is resolved with the path of the WEBP output file for reference.

An error will occur if both the baseFile and baseUrl options have been provided, the input file does not contain an SVG element, no width and/or height options were provided, and this information could not be derived from an input file, or a problem arises while reading the input file or writing the output file.

A Converter is created and closed to perform this operation using a this createConverter function below. If multiple files are being converted it is recommended to use createConverter to create a Converter and call its Converter#convertFile method multiple times instead.

Options

Option	Type	Default	Description
allowDeprecatedAttributes	boolean	true	Whether deprecated SVG element attributes should be retained in the SVG during conversion.
background	string	"#FFF" (White)	Background color to be used to fill transparent regions within the SVG.
baseFile	string	process.cwd()	Path of the file to be converted into a file URL to use for all relative URLs contained within the SVG. Cannot be used in conjunction with the baseUrl option.
baseUrl	string	"file:///${process.cwd()}"	Base URL to use for all relative URLs contained within the SVG. Cannot be used in conjunction with the baseFile option.
browser	object	None	Existing Browser instance provided by puppeteer that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. If specified, the launch option will be ignored.
closeBehavior	"close" | "disconnect" | "none"	"close"	Behavior when the converter is closed.
height	number | string	Derived	Height of the output to be generated. Derived from SVG input if omitted.
outputFilePath	string	Derived	Path of the file to which the WEBP output should be written to. Derived from inputFilePath if omitted.
quality	number	100	Quality of the output to be generated.
launch	object	None	Options that are to be passed directly to puppeteer when launching a new Browser that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. Ignored if the browser option is also specified.
page	object	None	Options that are to be passed directly to puppeteer when populating a Page with the SVG contents.
rounding	"ceil" | "floor" | "round"	"round"	Type of rounding to be applied to the width and height.
scale	number	1	Scale to be applied to the width and height (specified as options or derived).
width	number | string	Derived	Width of the output to be generated. Derived from SVG input if omitted.

Examples

import { convertFile} from "convert-svg-to-webp";
import { executablePath } from "puppeteer";

const main = async () => {
  const inputFilePath = "/path/to/my-image.svg";
  const outputFilePath = await convertFile(inputFilePath, {
    launch: { executablePath },
  });

  console.log(outputFilePath);
  //=> "/path/to/my-image.webp"
};

main().catch(console.error);

createConverter(options)

Creates an instance of Converter using the options provided.

When a Converter is created it must either be passed an existing Browser instance via the browser option or LaunchOptions via the launch option so that a browser instance can be created or connected; otherwise it will fail to be created.

If an existing Browser instance is being used you may want to also consider what happens if/when the Converter is closed (e.g. via Converter#close) as the default behavior is to close the browser and all open pages, even those not opened by the Converter. It can instead be instructed to either disconnect from the browser process or do nothing at all via the closeBehavior option.

Due to constraints within Chromium, the SVG input is first written to a temporary HTML file and then navigated to. This is because the default page for Chromium is using the chrome protocol so cannot load externally referenced files (e.g. that use the file protocol). Each invocation of Converter#convert or Converter#convertFile open their own Page and create their own temporary files to avoid conflicts with other asynchronous invocations, which is closed and deleted respectively once finished. This allows the returned Converter to safely process these calls concurrently.

A Converter uses its own BrowserContext to open each new Page. This ensures that the pages are isolated and that they can be closed by the Converter accordingly.

When calling either the Converter#convert or Converter#convertFiles the options parameter is the same as described above except that it is entirely optional and excludes the options that intersect with the options for createConverter (see below).

Options

Option	Type	Default	Description
browser	object	None	Existing Browser instance provided by puppeteer that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. If specified, the launch option will be ignored.
closeBehavior	"close" | "disconnect" | "none"	"close"	Behavior when the converter is closed.
launch	object	None	Options that are to be passed directly to puppeteer when launching a new Browser that is used to create a BrowserContext to open each new Page to capture a screenshot of an SVG to convert it into a WEBP. Ignored if the browser option is also specified.
page	object	None	Options that are to be passed directly to puppeteer when populating a Page with the SVG contents.

Examples

import { readdir } from "node:fs/promises";
import { createConverter } from "convert-svg-to-webp";
import { executablePath } from "puppeteer";

export const convertSvgFiles = async (dirPath) => {
  const converter = await createConverter({
    launch: { executablePath },
  });

  try {
    const filePaths = await readdir(dirPath);

    for (const filePath of filePaths) {
      await converter.convertFile(filePath);
    }
  } finally {
    await converter.close();
  }
};

Environment

This package supports the use of a CONVERT_SVG_LAUNCH_OPTIONS environment variable to act as a base for the launch option passed to the Converter constructor. 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