resvg-js

resvg-js is a Node.js and WebAssembly binding for resvg, a Rust SVG rendering library, that converts SVG documents into PNG raster images. It ships as prebuilt native addons for a wide matrix of platforms via napi-rs, so installing it requires no compiler toolchain, node-gyp, or postinstall build step.

Beyond basic rasterization, it exposes bounding-box calculation and crop-to-content APIs, custom font loading from files or in-memory buffers, deferred resolution of external <image> references, and cancellable async rendering. Its rendering core is shared with a separate WebAssembly build that runs the identical engine directly in browsers, making it one of the few SVG renderers usable identically on the server and client.

What You Get

• Native Node.js bindings prebuilt for a dozen platform/arch targets (Linux gnu/musl, macOS x64/arm64, Windows x64/ia32/arm64, Android) with no node-gyp or postinstall step
• A Resvg class that parses an SVG once and can be rendered, measured, and cropped repeatedly without re-parsing
• Bounding-box APIs (getBBox, innerBBox) and cropByBBox for cropping output to visible content, with optional padding and square cropping
• A separate WebAssembly build (@resvg/resvg-wasm) that runs the same Rust renderer directly in browsers
• Custom font loading via files, directories, or in-memory buffers, plus an optional system-fonts fallback
• Async rendering (renderAsync) with AbortSignal support for cancelling long-running conversions

Common Use Cases

• Generating Open Graph / social preview images at build time or in serverless functions
• Converting icon or illustration SVGs to PNG for platforms that don’t support SVG
• Server-side chart/diagram rasterization for PDF or email generation pipelines
• Rendering user-uploaded or dynamically generated SVGs to raster images in a browser via the Wasm build
• Cropping generated PNGs to their visible bounding box before further image processing

Under The Hood

Architecture The Rust core (src/lib.rs, options.rs, fonts.rs, error.rs) compiles to two distinct targets from one codebase via cfg gating: a native N-API addon (napi-rs) for Node.js and a WebAssembly module (wasm-bindgen) for browsers. The Resvg struct wraps a parsed usvg::Tree plus JsOptions, with core operations (render_inner, node_bbox, crop_by_bbox_inner) implemented once in shared inherent impls and exposed through thin, target-specific #[napi]/#[wasm_bindgen] impl blocks. Panic safety is handled explicitly: render_inner_catch_unwind wraps rendering in catch_unwind to convert Rust panics into catchable JS errors instead of crashing the process, and NAPI’s ObjectFinalize/adjust_external_memory hooks report Pixmap buffer sizes to V8 so the GC can reclaim memory more aggressively. The layout is a single-module Rust crate, layered by compile target rather than by directory, so a change to the shared rendering path propagates identically to both the Node and Wasm builds.

Tech Stack A Rust (2024 edition) core built with napi-rs v3, cross-compiled via the napi CLI to a dozen platform targets, alongside a separate wasm-bindgen 0.2 / wasm-pack build for WebAssembly. Rendering is delegated to a patched fork of resvg/usvg (pinned in [patch.crates-io]) plus pathfinder_geometry/pathfinder_content for bounding-box and stroke geometry, the png crate for encoding, a patched woff2 fork for font decompression, and mimalloc as the global allocator on non-Linux/non-wasm targets. JS-side tooling is TypeScript with Yarn 4 (Berry), ESLint (typescript-eslint + sonarjs + import plugins), Prettier, the ava test runner, and a benny-based benchmark suite comparing against sharp and svg2img.

Code Quality Around 1,800 lines of TypeScript tests span four spec files (index.spec.ts, index-bbox.spec.ts, index-panic.spec.ts, wasm.spec.ts) run via ava, covering rendering correctness via pixel comparison against jimp, bounding-box math, deliberately panic-inducing malformed SVG paths, and parity between the native and Wasm builds. A dedicated error.rs translates internal errors into typed NapiError/js_sys::Error, and rendering is wrapped in catch_unwind to turn Rust panics into recoverable JS exceptions. Naming stays consistent across the FFI boundary via explicit #[napi(js_name = ...)]/#[wasm_bindgen(js_name = ...)] annotations mapping snake_case Rust to camelCase JS. CI builds and tests across roughly a dozen target/host combinations; ESLint/typescript-eslint/sonarjs and cargo fmt enforce style on each side. Core Rust logic such as node_bbox and crop_by_bbox_inner has no dedicated Rust-level unit tests, relying instead on JS integration tests against the compiled binary.

What Makes It Unique resvg-js’s differentiator over pure-JS SVG rasterizers or bindings to librsvg/Cairo is shipping resvg, a from-scratch, spec-conformant Rust SVG renderer, as prebuilt native addons across a wide platform matrix with zero postinstall or node-gyp step, and building the identical Rust source a second time as WebAssembly so the same rendering engine runs client-side. Its API surface goes beyond simple SVG-in/PNG-out conversion with element-aware cropping (getBBox/innerBBox/cropByBBox) and deferred external-image resolution (imagesToResolve/resolveImage) for callers that want to fetch referenced images themselves.