@resvg/resvg-js

What is @resvg/resvg-js?

@resvg/resvg-js is an npm package that provides a JavaScript interface for the Resvg library, which is used for rendering SVG files. It allows you to convert SVG files to various formats, manipulate SVG elements, and perform other SVG-related tasks.

What are @resvg/resvg-js's main functionalities?

Render SVG to PNG

This feature allows you to render an SVG file to a PNG image. The code sample demonstrates how to load SVG data, render it using Resvg, and save the output as a PNG file.

const { Resvg } = require('@resvg/resvg-js');
const fs = require('fs');

const svgData = '<svg>...</svg>'; // Your SVG data here
const resvg = new Resvg(svgData);
const pngData = resvg.render().asPng();
fs.writeFileSync('output.png', pngData);

Render SVG to JPEG

This feature allows you to render an SVG file to a JPEG image. The code sample demonstrates how to load SVG data, render it using Resvg, and save the output as a JPEG file.

const { Resvg } = require('@resvg/resvg-js');
const fs = require('fs');

const svgData = '<svg>...</svg>'; // Your SVG data here
const resvg = new Resvg(svgData);
const jpegData = resvg.render().asJpeg();
fs.writeFileSync('output.jpeg', jpegData);

Render SVG to WebP

This feature allows you to render an SVG file to a WebP image. The code sample demonstrates how to load SVG data, render it using Resvg, and save the output as a WebP file.

const { Resvg } = require('@resvg/resvg-js');
const fs = require('fs');

const svgData = '<svg>...</svg>'; // Your SVG data here
const resvg = new Resvg(svgData);
const webpData = resvg.render().asWebp();
fs.writeFileSync('output.webp', webpData);

Other packages similar to @resvg/resvg-js

sharp

Sharp is a high-performance image processing library for Node.js. It supports a wide range of image formats, including SVG, and can convert SVG files to other formats like PNG, JPEG, and WebP. Compared to @resvg/resvg-js, Sharp offers more general image processing capabilities but may not be as specialized in SVG rendering.

svg2img

svg2img is a simple library for converting SVG files to various image formats such as PNG, JPEG, and WebP. It is similar to @resvg/resvg-js in terms of functionality but may not offer the same level of performance and customization options.

canvg

Canvg is a library that allows you to render SVG files on an HTML5 canvas. It can be used to convert SVG to raster images by drawing the SVG on a canvas and then exporting the canvas content. While it provides similar functionality to @resvg/resvg-js, it is more focused on web-based applications and may not be as efficient for server-side rendering.

README

resvg-js

resvg-js is a high-performance SVG renderer and toolkit, powered by Rust based resvg, with Node.js backend using napi-rs, also a pure WebAssembly backend.

Please use all lowercase resvg-js when referencing project names.

Features

• Fast, safe and zero dependencies, with correct output.
• Convert SVG to PNG, includes cropping, scaling and setting the background color.
• Support system fonts and custom fonts in SVG text.
• v2: Gets the width and height of the SVG and the generated PNG.
• v2: Support for outputting simplified SVG strings, such as converting shapes(rect, circle, etc) to <path>.
• v2: Support WebAssembly.
• v2: Support to get SVG bounding box and crop according to bounding box.
• v2: Support for loading images of external links in <image>.
• No need for node-gyp and postinstall, the .node file has been compiled for you.
• Cross-platform support, including Apple M Chips.
• Support for running as native addons in Deno.

Installation

Node.js

npm i @resvg/resvg-js

Browser(Wasm)

<script src="https://unpkg.com/@resvg/resvg-wasm"></script>

Docs

• Node.js see index.d.ts
• Wasm see wasm/index.d.ts

Example

Node.js Example

This example will load Source Han Serif, and then render the SVG to PNG.

node example/index.js

Loaded 1 font faces in 0ms.
Font './example/SourceHanSerifCN-Light-subset.ttf':0 found in 0.006ms.
✨ Done in 55.65491008758545 ms

Deno Example

deno run --unstable --allow-read --allow-write --allow-ffi example/index-deno.js

[2022-11-16T15:03:29Z DEBUG resvg_js::fonts] Loaded 1 font faces in 0.067ms.
[2022-11-16T15:03:29Z DEBUG resvg_js::fonts] Font './example/SourceHanSerifCN-Light-subset.ttf':0 found in 0.001ms.
Original SVG Size: 1324 x 687
Output PNG Size  : 1200 x 623
✨ Done in 66 ms

SVG	PNG

Usage

Node.js

const { promises } = require('fs')
const { join } = require('path')
const { Resvg } = require('@resvg/resvg-js')

async function main() {
  const svg = await promises.readFile(join(__dirname, './text.svg'))
  const opts = {
    background: 'rgba(238, 235, 230, .9)',
    fitTo: {
      mode: 'width',
      value: 1200,
    },
    font: {
      fontFiles: ['./example/SourceHanSerifCN-Light-subset.ttf'], // Load custom fonts.
      loadSystemFonts: false, // It will be faster to disable loading system fonts.
      // defaultFontFamily: 'Source Han Serif CN Light', // You can omit this.
    },
  }
  const resvg = new Resvg(svg, opts)
  const pngData = resvg.render()
  const pngBuffer = pngData.asPng()

  console.info('Original SVG Size:', `${resvg.width} x ${resvg.height}`)
  console.info('Output PNG Size  :', `${pngData.width} x ${pngData.height}`)

  await promises.writeFile(join(__dirname, './text-out.png'), pngBuffer)
}

main()

Bun

Starting with Bun 0.8.1, resvg-js can be run directly in Bun without any modification to the JS files, and is fully compatible with the syntax in Node.js.

bun example/index.js

Deno

Starting with Deno 1.26.1, there is support for running Native Addons directly from Node.js. This allows for performance that is close to that found in Node.js.

deno run --unstable --allow-read --allow-write --allow-ffi example/index-deno.js

import * as path from 'https://deno.land/std@0.159.0/path/mod.ts'
import { Resvg } from 'npm:@resvg/resvg-js'
const __dirname = path.dirname(path.fromFileUrl(import.meta.url))

const svg = await Deno.readFile(path.join(__dirname, './text.svg'))
const opts = {
  fitTo: {
    mode: 'width',
    value: 1200,
  },
}

const t = performance.now()
const resvg = new Resvg(svg, opts)
const pngData = resvg.render()
const pngBuffer = pngData.asPng()
console.info('Original SVG Size:', `${resvg.width} x ${resvg.height}`)
console.info('Output PNG Size  :', `${pngData.width} x ${pngData.height}`)
console.info('✨ Done in', performance.now() - t, 'ms')

await Deno.writeFile(path.join(__dirname, './text-out-deno.png'), pngBuffer)

WebAssembly

This package also ships a pure WebAssembly artifact built with wasm-bindgen to run in browsers.

Browser

<script src="https://unpkg.com/@resvg/resvg-wasm"></script>
<script>
  (async function () {
    // The Wasm must be initialized first
    await resvg.initWasm(fetch('https://unpkg.com/@resvg/resvg-wasm/index_bg.wasm'))

    const font = await fetch('./fonts/Pacifico-Regular.woff2')
    if (!font.ok) return

    const fontData = await font.arrayBuffer()
    const buffer = new Uint8Array(fontData)

    const opts = {
      fitTo: {
        mode: 'width', // If you need to change the size
        value: 800,
      },
      font: {
        fontBuffers: [buffer], // New in 2.5.0, loading custom fonts
      },
    }

    const svg = '<svg> ... </svg>' // Input SVG, String or Uint8Array
    const resvgJS = new resvg.Resvg(svg, opts)
    const pngData = resvgJS.render(svg, opts) // Output PNG data, Uint8Array
    const pngBuffer = pngData.asPng()
    const svgURL = URL.createObjectURL(new Blob([pngData], { type: 'image/png' }))
    document.getElementById('output').src = svgURL
  })()
</script>

See playground, it is also possible to call Wasm in Node.js, but it is slower.

Sample Benchmark

npm i benny@3.x sharp@0.x @types/sharp svg2img@0.x
npm run bench

Running "resize width" suite...
  resvg-js(Rust):
    12 ops/s

  sharp:
    9 ops/s

  skr-canvas(Rust):
    7 ops/s

  svg2img(canvg and node-canvas):
    6 ops/s

Support matrix

	Node.js 12	Node.js 14	Node.js 16	Node.js 18	npm
Windows x64	✓	✓	✓	✓
Windows x32	✓	✓	✓	✓
Windows arm64	✓	✓	✓	✓
macOS x64	✓	✓	✓	✓
macOS arm64(M1)	✓	✓	✓	✓
Linux x64 gnu	✓	✓	✓	✓
Linux x64 musl	✓	✓	✓	✓
Linux arm gnu	✓	✓	✓	✓
Linux arm64 gnu	✓	✓	✓	✓
Linux arm64 musl	✓	✓	✓	✓
Android arm64	✓	✓	✓	✓
Android armv7	✓	✓	✓	✓

Test or Contributing

• Install latest Rust

• Install Node.js@10+ which fully supported Node-API

• Install wasm-pack

  curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
  

  Normally wasm-pack will install wasm-bindgen automatically, but if the installation fails due to network reasons, please try to install it manually.

  cargo install wasm-bindgen-cli
  

  On computers with Apple M chips, the following error message may appear:

  Error: failed to download from https://github.com/WebAssembly/binaryen/releases/download/version_90/binaryen-version_90-x86_64-apple-darwin.tar.gz

  Please install binaryen manually:

  brew install binaryen
  

Build Node.js bindings

npm i
npm run build
npm test

Build WebAssembly bindings

npm i
npm run build:wasm
npm run test:wasm

Roadmap

I will consider implementing the following features, if you happen to be interested, please feel free to discuss with me or submit a PR.

• Support async API
• Upgrade to napi-rs v2
• Support WebAssembly
• Output usvg-simplified SVG string
• Support for getting SVG Bounding box
• Support for generating more lossless bitmap formats, e.g. avif, webp, JPEG XL

Release package

We use GitHub actions to automatically publish npm packages.

# 1.0.0 => 1.0.1
npm version patch

# or 1.0.0 => 1.1.0
npm version minor

License

Please use all lowercase resvg-js when referencing project names.

MPLv2.0

Copyright (c) 2021-present, yisibl(一丝)

Changelog

[2.5.0] - 2023-10-16

Added

Now we can finally loading custom fonts in Wasm, including the WOFF2 format (see playground), thanks to the high-performance woff2-rs.

In addition, we implemented smarter default font family fallback. the defaultFontFamily option can now be omitted. We'll read the font-family from the incoming fonts and set it to the default.

<script src="https://unpkg.com/@resvg/resvg-wasm"></script>
<script>
  ;(async function () {
    await resvg.initWasm(fetch('https://unpkg.com/@resvg/resvg-wasm/index_bg.wasm'))

    const font = await fetch('./fonts/Pacifico-Regular.woff2')
    if (!font.ok) return

    const fontData = await font.arrayBuffer()
    const buffer = new Uint8Array(fontData)

    const opts = {
      font: {
        fontBuffers: [buffer], // New in 2.5.0, loading custom fonts.
        // defaultFontFamily: 'Pacifico', // You can omit this.
      },
    }

    const svg = '<svg> ... </svg>' // Input SVG, String or Uint8Array
    const resvgJS = new resvg.Resvg(svg, opts)
    const pngData = resvgJS.render(svg, opts) // Output PNG data, Uint8Array
    const pngBuffer = pngData.asPng()
    const svgURL = URL.createObjectURL(new Blob([pngData], { type: 'image/png' }))
    document.getElementById('output').src = svgURL
  })()
</script>

• feat: improve custom loaded fonts. Thanks to @yisibl #209
• feat: support for loading custom fonts in Wasm, via the fontBuffers option. Thanks to @antmelnyk #217
• feat: support loading WOFF2 font in Wasm. Thanks to @yisibl #220
• chore: Wasm uses the same logic as Node.js to find the default font family.Thanks to @yisibl #252

We have improved the upstream svgtypes#14, allow parsing of float rgb()/rgba() values from CSS Color 4 draft like rgb(3.14, 110, 201).

• fix(deps): update rust crate svgtypes to 0.12.0. Thanks to @yisibl #266

Changed

• test: fix test image timeout. #262