convert-svg-to-jpeg
A Node.js package for converting SVG to JPEG using headless Chromium.
Install
Install using npm:$ npm install --save convert-svg-to-jpegYou'll need to have at least Node.js 12.20.0 or newer.
If you want to use the command line interface you'll most likely want to install it globally so that you can run
convert-svg-to-jpeg from anywhere:$ npm install --global convert-svg-to-jpegCLI
Usage: convert-svg-to-jpeg [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 JPEG output when processing STDIN
--height <value> specify height for JPEG
--puppeteer <json> specify a json object for puppeteer.launch options
--rounding <type> specify type of rounding to apply to dimensions
--scale <value> specify scale to apply to dimensions [1]
--width <value> specify width for JPEG
--quality <value> specify quality for JPEG [100]
-h, --help output usage information- Pass SVG files to be converted to JPEG files as command arguments
`image.svg -> image.jpeg`)- Pipe SVG buffer to be converted to JPEG to command via STDIN
--filename option is passed, the JPEG will be written to a file resolved using its value
Otherwise, the JPEG will be streamed to STDOUTAPI
convert(input[, options])
Converts the specified input SVG into a JPEG 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 JPEG 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.Options
| Option | Type | Default | Description | |-----------------------------|------------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| |allowDeprecatedAttributes | Boolean | true | Whether deprecated SVG element attributes should be retained in the SVG during conversion. |
| background | String | N/A | Background color to be used to fill transparent regions within the SVG. White will be used if omitted. |
| baseFile | String | N/A | 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:///path/to/cwd" | Base URL to use for all relative URLs contained within the SVG. Cannot be used in conjunction with the baseFile option. |
| height | Number/String | N/A | Height of the output to be generated. Derived from SVG input if omitted. |
| puppeteer | Object | N/A | Options that are to be passed directly to puppeteer.launch when creating the Browser instance. |
| quality | Number | 100 | Quality of the output to be generated. |
| 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 | N/A | Width of the output to be generated. Derived from SVG input if omitted. |The
puppeteer option is not available when calling this method on a Converter instance created using
createConverter.Example
const { convert } = require('convert-svg-to-jpeg');
const express = require('express');
const app = express();
app.post('/convert', async(req, res) => {
const jpeg = await convert(req.body);
res.set('Content-Type', 'image/jpeg');
res.send(jpeg);
});
app.listen(3000);convertFile(inputFilePath[, options])
Converts the SVG file at the specified path into a JPEG 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 JPEG 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 input file,
or a problem arises while reading the input file or writing the output file.Options
Has the same options as the standardconvert method but also supports the following additional options:| Option | Type | Default | Description | |------------------|--------|---------|----------------------------------------------------------------------------------------------------------| |
outputFilePath | String | N/A | Path of the file to which the JPEG output should be written to. Derived from input file path if omitted. |Example
const { convertFile} = require('convert-svg-to-jpeg');
(async() => {
const inputFilePath = '/path/to/my-image.svg';
const outputFilePath = await convertFile(inputFilePath);
console.log(outputFilePath);
//=> "/path/to/my-image.jpeg"
})();createConverter([options])
Creates an instance of Converter using the options provided.It is important to note that, after the first time either
Converter#convert or Converter#convertFile are called, a
headless Chromium instance will remain open until Converter#destroy is called. This is done automatically when using
the API convert methods, however, when using Converter directly, it is the responsibility of the caller. Due to the
fact that creating browser instances is expensive, this level of control allows callers to reuse a browser for multiple
conversions. It's not recommended to keep an instance around for too long, as it will use up resources.Options
| Option | Type | Default | Description | |-------------|--------|---------|----------------------------------------------------------------------------------------------------| |puppeteer | Object | N/A | Options that are to be passed directly to puppeteer.launch when creating the Browser instance. |Example
const { createConverter } = require('convert-svg-to-jpeg');
const fs = require('fs');
const util = require('util');
const readdir = util.promisify(fs.readdir);
async function convertSvgFiles(dirPath) {
const converter = createConverter();
try {
const filePaths = await readdir(dirPath);
for (const filePath of filePaths) {
await converter.convertFile(filePath);
}
} finally {
await converter.destroy();
}
}Other Formats
If you would like to convert an SVG into a format other than JPEG, 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 © 2022 neocoticSee LICENSE.md for more information on our MIT license.
