convert-svg-to-png

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

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

Install

Install using npm:

npm install --save convert-svg-to-png

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

Usage

convert(input, options)

Converts the specified input SVG into a PNG 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 PNG 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

Examples

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

const app = express();

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

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

app.listen(3000);

convertFile(inputFilePath, options)

Converts the SVG file at the specified path into a PNG 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 PNG 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

Examples

import { convertFile} from "convert-svg-to-png";
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.png"
};

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

Examples

import { readdir } from "node:fs/promises";
import { createConverter } from "convert-svg-to-png";
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:

1. Connect this package to a Firefox instance; however, some features may not be supported due to their lack of support in WebDriver BiDi.
2. Run this package on Linux (e.g. Ubuntu), even if it's just within Docker, will have noticeable improvements of macOS rendering.
3. 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 PNG, 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.

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

Version 0.7.0, 2025.06.14

• Breaking Change: All packages now require Node.js v22 or newer
• Breaking Change: Change createConverter to be async
• Breaking Change: Rename Converter#destroy to Converter#close
• Breaking Change: Rename puppeteer option to launch
• Breaking Change: Change all convert-svg-to-<FORMAT> packages to only depend on puppeteer-core so consumers must depend on puppeteer and pass either a Browser instance via the browser option or LaunchOptions via the launch option to convert, convertFile, and createConverter functions
• Breaking Change: Remove CLI support from all convert-svg-to-<FORMAT> packages and create new convert-svg-to-<FORMAT>-cli packages for that purpose (which come with puppeteer dependency to ensure browser is downloaded and installed for ease-of-use)
• Rewrite the entire codebase in TypeScript and support both ESM and CJS usage
• Add browser option to convert, convertFile, and createConverter functions to accept optional Browser instance
• Add closeBehavior option to convert, convertFile, and createConverter functions to control the behavior when Converter#close is called
• Add page option to convert, convertFile, and createConverter functions to accept optional options to be passed to puppeteer-core when creating a page
• Add support for CONVERT_SVG_LAUNCH_OPTIONS environment variable to be merged with launch option
• Change Converter to create and use BrowserContext per instance to use when opening new pages to ensure they are isolated and that they can be closed by the Converter accordingly
• Change Converter#convert and Converter#convertFile to create a new temporary file and open a new Page per invocation to support safe concurrent invocations of these methods on the same Converter instance
• Sanitize attributes on deeply nested SVG elements
• Apply the round option to SVG width and height when applying the scale option
• Improve documentation
• Improve the developer experience for contributors with better tooling
• Deprecate convert-svg-test-helper and create new convert-svg-core-test package as a replacement
• Create new convert-svg-core-cli package to support CLI packages
• Many internal changes to convert-svg-core
• Bump all dependencies to latest versions

Version 0.6.4, 2022.06.07

• Convert only first SVG element from input #86 2bbc498

Version 0.6.3, 2022.06.06

• Retain only allowed attributes from SVG input #84 a43dffa

Version 0.6.2, 2022.05.29

• Add convert-svg-to-webp package 812ea66
• Strip onload attribute from SVG input #81 7e6031a

Version 0.6.1, 2022.04.29

• Bump cheerio dependency to latest v1 RC avoid vulnerable dependency

Version 0.6.0, 2022.04.28

• Breaking Change: All packages now require Node.js version 12.20.0 or newer
• Support UTF-8 characters in SVG
• Support SVG dimensions (width, height) that use pt units
• Add rounding API and CLI option to control how dimensions are rounded (defaults to "round")
• Fix CVE-2021-23631 by improving input validation
• quality CLI option for JPEG not passed correctly #65
• Bump dependencies (incl. major for Puppeteer)
• Bump devDependencies
• Skip inconsistent tests

Version 0.5.0, 2018.11.23

• moved from !ninja to neocotic ad5aa55
• modified CI to now target Node.js 8, 10, and 11 63fcb27
• bump dependencies 6daedb1
• bumped devDependenices 3a8ae85
• fixed linting errors 96e7e06
• fixed broken tests by regenerating expected fixtures bf34770
• preventing lerna breaking build when calling "npm ci" on bootstrap 1391071
• skipped tests that were causing CI build to fail intermittently cdf43c0

Version 0.4.0, 2018.02.05

• Bump Puppeteer to v1 #32
• Replace chai with assert #34

Version 0.3.3, 2017.12.08

• Add puppeteer.launch options available into CLI #29

Version 0.3.2, 2017.11.21

• Error being thrown caused by lost context for CLI #24
• Pass custom arguments to puppeteer #25 #27
• Bump puppeteer to v0.13.0 #26

Version 0.3.1, 2017.11.03

• Error thrown as context is lost for API methods when using destructuring imports #22

Version 0.3.0, 2017.11.03

• Add option to control background color #14
• Remove all controllable short options for CLI #15 (breaking change)
• Split package up into multiple packages to be more modular #17 (breaking change)
• Add convert-svg-to-jpeg package to convert SVG to JPEG #18

Version 0.2.0, 2017.10.29

• Add CLI & convertFile method to API #2 #8
• Add scale option #3 #11
• Throw error when baseFile & baseUrl options are both specified #4 (breaking change)
• Change source/target terminology to input/output #6
• Expose Converter class as primary export #9 (breaking change)

Version 0.1.0, 2017.10.19

• Initial release