@napi-rs/canvas
v1.1.1
Published
Canvas for Node.js with skia backend
Downloads
191,835,916
Readme
skr canvas
🚀 Help me to become a full-time open-source developer by sponsoring me on Github
Google Skia binding to Node.js via Node-API, 0 System dependencies!
Install
yarn add @napi-rs/canvas
npm install @napi-rs/canvasSupport matrix
System requirement
arm64
cortex-a57 or newer CPU architecture on Linux.
All Apple M chips on macOS.
armv7
cortex-a7 or newer CPU architecture.
glibc
Since Skia relies on the glibc 2.18 API, you need to have at least glibc version >= 2.18 on your system.
Note: the armv7 (linux-arm-gnueabihf) packages from 0.1.66 to 1.1.0 need
a newer glibc (0.1.66 needs 2.28, 1.1.0 needs 2.30). Later versions need
glibc 2.18, like the other targets.
AWS Lambda usage
To use this library on Lambda you will need to use a Lambda layer.
You can simply attach a lambda layer by getting an ARN from Canvas-Lambda-Layer
Make sure to exclude
@napi-rs/canvaswhile bundling your Lambda.
Usage
const { promises } = require('node:fs')
const { join } = require('node:path')
const { createCanvas, loadImage } = require('@napi-rs/canvas')
const canvas = createCanvas(300, 320)
const ctx = canvas.getContext('2d')
ctx.lineWidth = 10
ctx.strokeStyle = '#03a9f4'
ctx.fillStyle = '#03a9f4'
// Wall
ctx.strokeRect(75, 140, 150, 110)
// Door
ctx.fillRect(130, 190, 40, 60)
// Roof
ctx.beginPath()
ctx.moveTo(50, 140)
ctx.lineTo(150, 60)
ctx.lineTo(250, 140)
ctx.closePath()
ctx.stroke()
async function main() {
// load images from disk or from a URL
const catImage = await loadImage('path/to/cat.png')
const dogImage = await loadImage('https://example.com/path/to/dog.jpg')
ctx.drawImage(catImage, 0, 0, catImage.width, catImage.height)
ctx.drawImage(dogImage, canvas.width / 2, canvas.height / 2, dogImage.width, dogImage.height)
// export canvas as image
const pngData = await canvas.encode('png') // JPEG, AVIF and WebP are also supported
// encoding in libuv thread pool, non-blocking
await promises.writeFile(join(__dirname, 'simple.png'), pngData)
}
main()
Image metadata
toBuffer, encode and encodeSync can write the resolution (DPI) and a few text fields into PNG and JPEG output. Put them in the options object:
const png = canvas.toBuffer('image/png', {
resolution: 300, // pixels per inch, the same option as node-canvas
title: 'Floor plan',
author: 'Jane Doe',
description: 'Ground floor, 1:100',
})
// JPEG: use encode / encodeSync to set the quality as well
const jpeg = await canvas.encode('jpeg', { quality: 90, resolution: 300, copyright: '© 2026 Jane Doe' })| Option | PNG | JPEG |
| ------------- | ------------------ | ---------------------------- |
| resolution | pHYs chunk | JFIF density (dots per inch) |
| title | Title text chunk | XMP dc:title |
| author | Author | XMP dc:creator |
| description | Description | XMP dc:description |
| copyright | Copyright | XMP dc:rights |
| software | Software | XMP xmp:CreatorTool |
| comment | Comment | COM segment |
WebP, AVIF and GIF output ignore these options. toDataURL, toDataURLAsync, toBlob, convertToBlob, encodeStream and savePng never write metadata. To save a file with metadata, write the Buffer from toBuffer or encode. With an options object, toBuffer('image/jpeg', ...) encodes at quality 92; use encode or encodeSync for another quality.
Text rendering
By default text is drawn the same way on every OS. Every font is drawn with FreeType, with Skia's default text gamma, no LCD (subpixel) text and one font family table (the one Linux uses).
Text gives the same pixels and the same measureText results on macOS, Linux and Windows when all of these are true:
ctx.fontnames only fonts you registered. The canvas default10px sans-serif, the other generic families and names likeArialuse installed fonts, unless you registered a font under that name.- Your registered fonts have every character you draw. A character they lack is taken from an installed font.
- You set
ctx.lang, for example to'en'. The default'inherit'follows the host language. - You use the default
'portable'renderer, notsetTextRenderer('system'). - The
FREETYPE_PROPERTIESenv var is not set.
x64 and arm64 builds can still differ by 1 color level on some edge pixels.
const { GlobalFonts } = require('@napi-rs/canvas')
// A name no OS installs
GlobalFonts.registerFromPath('./fonts/Lato-Regular.ttf', 'MyLato')
ctx.font = '20px MyLato'
ctx.lang = 'en'A name registered over an installed family (for example Helvetica) works like a CSS @font-face in Chrome: only font lists that name it use it, for every style (bold and italic are made from the faces you registered when you registered no bold or italic face). The generic families, such as sans-serif, keep the installed family. To change a generic family, register the font under the keyword itself:
GlobalFonts.registerFromPath('./fonts/Lato-Regular.ttf', 'sans-serif')These still depend on the OS and the machine:
- Installed fonts. Names like
ArialorHelvetica, and the generic families (sans-serif,serif,monospace,system-ui, the canvas default10px sans-serif) resolve to whatever is installed. - Characters your registered fonts lack. They are taken from an installed font (the ones
loadSystemFontsandloadFontsFromDirload, or the OS font folder) that has them, else they draw as boxes. A font youregisterorregisterFromPathis never used for a character another font lacks, as in Chrome: to give a host without fonts a fallback font, load it withloadFontsFromDir. - The
ex,ch,capand line-height units inside SVG images use an installed default font. - Lottie (Skottie) text uses installed fonts.
- PDF font embedding depends on the build target.
- x64 and arm64 builds can differ by 1 color level on some edge pixels.
- A
FREETYPE_PROPERTIESenv var changes FreeType's hinting. - The host language. The default
ctx.lang('inherit') follows the OS UI language (the macOS language list, the Windows user locale, orLANGUAGE/LC_ALL/LC_MESSAGES/LANGelsewhere), as Chrome does. It changesloclglyphs, case mapping (small-capsundertr) and CJK punctuation spacing. Setctx.lang(for example'en') to pin it. The installed font picked for a Han character still follows the host language unlessctx.langnames a CJK language (for example'ja'or'zh-Hans'). On macOS withsetTextRenderer('system'), the generic families also follow aja,ko,zh-CN,zh-TW,ar,heorfaUI language whateverctx.langis, as in Chrome (serifis Hiragino Mincho ProN under a Japanese UI).
Set DISABLE_SYSTEM_FONTS_LOAD=1 to keep installed fonts out of GlobalFonts.families. By default they can still be found by name, on every OS.
setTextRenderer()
setTextRenderer('system') draws text the way Chrome does on each OS: CoreText on macOS (with CoreText's installed fonts and fallback), Fontations on Linux and FreeType on Windows, plus each OS's text gamma, LCD text on opaque macOS canvases, Chrome's per-OS font families and the macOS metric rules. This was the default in 1.0.12 and 1.0.13. 'portable' is the default.
const { setTextRenderer, getTextRenderer } = require('@napi-rs/canvas')
setTextRenderer('system')
getTextRenderer() // 'system'It applies to the whole process. Call it once at startup, before you create canvases. setTextRenderer('portable') switches back. Any other value throws a TypeError. A canvas created before the switch keeps its old text gamma until you set its width or height. A ctx.font value set before the switch keeps its parsed form (sizes in ex, ch and other font-relative units, and on macOS the BlinkMacSystemFont to system-ui rewrite), so set ctx.font again after the switch.
Behavior change (#1402): text on macOS and Linux is drawn the way Windows draws it, so pixels and
measureTextresults differ from 1.0.12 and 1.0.13. On macOS, the installed fonts are FreeType faces again (as in 1.0.11), read from/System/Library/Fonts,/Library/Fontsand~/Library/Fonts; CoreText's per-character fallback is off, andsans-serif,serifandmonospacemap to Arial, Times New Roman and the Linux monospace list. On macOS,DISABLE_SYSTEM_FONTS_LOADno longer hides installed fonts from name lookup, as on Linux and Windows and before 1.0.12; it only keeps them out ofGlobalFonts.families. CallsetTextRenderer('system')to draw with each OS's own font renderer and installed fonts again, as 1.0.12 and 1.0.13 did. Both renderers now shape text the way Chrome does, so the output is not the same as in 1.0.12 and 1.0.13.
Behavior change: a character no font of the font list has is taken from an installed font, as Chrome's font cache takes it from the platform's fonts. This applies to the portable renderer on every OS and to the system renderer off macOS (on macOS, CoreText still picks first). The font is chosen the way Chrome on Windows chooses it: a bold or italic list first tries its first family at the normal style, then the font Windows names for the character's script (on macOS, the font Chrome's CoreText fallback names for it), then the first installed family, by name, that has the character. Before, such a character drew as a box (the first font's
.notdef). Private use characters still draw as boxes.
Behavior change: SVG text (SVG images, the SVG images nested in them, and
convertSVGTextToPath) takes a character its first font lacks from the next family of itsfont-familylist, then from the system's fonts, as canvas text does. Chrome does the same. Before, the whole text used the first font, and a character it lacks drew as a box. Text with no such character draws the same as before.convertSVGTextToPathnow reads the document the way an SVG image does (<style>sheets,var(),<use>and the other CSS rules), so its output matches what the SVG image draws. A document that is not well-formed UTF-8 XML is read as before, with only the first family of eachfont-familylist.
Behavior change: the default
ctx.lang,'inherit', follows the host language, as Chrome does. Before, it meant no language. Text whose font has language-specific glyphs or spacing can draw and measure differently on hosts with different UI languages; setctx.langto pin it.
Behavior change: SVG text whose family lacks the bold or italic face it asks for draws a synthetic bold or italic, with the rules canvas text uses: a registered font is bolded at
font-weight600 and up and slanted foritalicandobliqueunless it has that face (or awghtaxis above 400, or aslntaxis); an installed font follows its own faces. Chrome does the same. The advances do not change, so the text does not move; the glyphs are heavier or slanted, andconvertSVGTextToPathoutlines grow to match. Before, SVG text drew the regular face for every style.
Emoji text
const { writeFileSync } = require('fs')
const { join } = require('path')
const { createCanvas, GlobalFonts } = require('@napi-rs/canvas')
GlobalFonts.registerFromPath(join(__dirname, '..', 'fonts', '[email protected]'), 'Apple Emoji')
GlobalFonts.registerFromPath(join(__dirname, '..', '__test__', 'fonts', 'COLRv1.ttf'), 'COLRv1')
console.info(GlobalFonts.families)
const canvas = createCanvas(760, 360)
const ctx = canvas.getContext('2d')
ctx.font = '50px Apple Emoji'
ctx.strokeText('😀😃😄😁😆😅😂🤣☺️😊😊😇', 50, 150)
ctx.font = '100px COLRv1'
ctx.fillText('abc', 50, 300)
const b = canvas.toBuffer('image/png')
writeFileSync(join(__dirname, 'draw-emoji.png'), b)
Features
Path2D
new Path2D()
new Path2D(path: Path2D)
// new Path2D('M108.956,403.826c0,0,0.178,3.344-1.276,3.311 c-1.455-0.033-30.507-84.917-66.752-80.957C40.928,326.18,72.326,313.197,108.956,403.826z')
new Path2D(path: string)export interface DOMMatrix2DInit {
a: number
b: number
c: number
d: number
e: number
f: number
}
export class Path2D {
constructor(path?: Path2D | string)
addPath(path: Path2D, transform?: DOMMatrix2DInit): void
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void
arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void
bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void
closePath(): void
ellipse(
x: number,
y: number,
radiusX: number,
radiusY: number,
rotation: number,
startAngle: number,
endAngle: number,
anticlockwise?: boolean,
): void
lineTo(x: number, y: number): void
moveTo(x: number, y: number): void
quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void
rect(x: number, y: number, w: number, h: number): void
// PathKit methods
op(path: Path2D, operation: PathOp): Path2D
toSVGString(): string
getFillType(): FillType
getFillTypeString(): string
setFillType(type: FillType): void
simplify(): Path2D
asWinding(): Path2D
stroke(stroke?: StrokeOptions): Path2D
transform(transform: DOMMatrix2DInit): Path2D
getBounds(): [left: number, top: number, right: number, bottom: number]
computeTightBounds(): [left: number, top: number, right: number, bottom: number]
trim(start: number, end: number, isComplement?: boolean): Path2D
round(radius: number): Path2D
equals(path: Path2D): boolean
}PathKit
PathKit is a toolset for manipulating Path in Skia, supporting quadratic beziers, cubic beziers and conics.
The main features are.
Path Operation
.op(path, PathOp)
const pathOne = new Path2D(
'M8 50H92C96.4183 50 100 53.5817 100 58V142C100 146.418 96.4183 150 92 150H8C3.58172 150 0 146.418 0 142V58C0 53.5817 3.58172 50 8 50Z',
)
const pathTwo = new Path2D(
'"M58 0H142C146.418 0 150 3.58172 150 8V92C150 96.4183 146.418 100 142 100H58C53.5817 100 50 96.4183 50 92V8C50 3.58172 53.5817 0 58 0Z',
)
pathOne.op(pathTwo, PathOp.Intersect).toSVGString()
// => "M100 100L58 100C53.5817 100 50 96.4183 50 92L50 50L92 50C96.4183 50 100 53.5817 100 58L100 100Z"- Union, subtract the op path from the first path
- Difference, intersect the two paths
- ReverseDifference, union (inclusive-or) the two paths
- Intersect, exclusive-or the two paths
- XOR, subtract the first path from the op path
Covert FillType in Path
.asWinding()
You can convert fill-rule="evenodd" to fill-rule="nonzero" in SVG.
This is useful for OpenType font-related tools, as fill-rule="nonzero" is only supported in OpenType fonts.

const pathCircle = new Path2D(
'M24.2979 13.6364H129.394V40.9091H24.2979L14.6278 27.2727L24.2979 13.6364ZM21.9592 0C19.0246 0 16.2716 1.42436 14.571 3.82251L1.67756 22.0043C-0.559186 25.1585 -0.559186 29.387 1.67756 32.5411L14.571 50.7227C16.2716 53.1209 19.0246 54.5455 21.9592 54.5455H70.4673V68.1818H16.073C11.0661 68.1818 7.00728 72.2518 7.00728 77.2727V113.636C7.00728 118.657 11.0661 122.727 16.073 122.727H70.4673V150H84.0658V122.727H128.041C130.975 122.727 133.729 121.303 135.429 118.905L148.323 100.723C150.559 97.5686 150.559 93.3405 148.323 90.1864L135.429 72.0045C133.729 69.6064 130.975 68.1818 128.041 68.1818H84.0658V54.5455H133.927C138.934 54.5455 142.993 50.4755 142.993 45.4545V9.09091C142.993 4.07014 138.934 0 133.927 0H21.9592ZM125.702 109.091H20.6058V81.8182H125.702L135.372 95.4545L125.702 109.091Z',
)
pathCircle.setFillType(FillType.EvenOdd)
pathCircle.asWinding().toSVGString()
// => "M24.2979 13.6364L129.394 13.6364L129.394 40.9091L24.2979 40.9091L14.6278 27.2727L24.2979 13.6364ZM21.9592 0C19.0246 0 16.2716 1.42436 14.571 3.82251L1.67756 22.0043C-0.559186 25.1585 -0.559186 29.387 1.67756 32.5411L14.571 50.7227C16.2716 53.1209 19.0246 54.5455 21.9592 54.5455L70.4673 54.5455L70.4673 68.1818L16.073 68.1818C11.0661 68.1818 7.00728 72.2518 7.00728 77.2727L7.00728 113.636C7.00728 118.657 11.0661 122.727 16.073 122.727L70.4673 122.727L70.4673 150L84.0658 150L84.0658 122.727L128.041 122.727C130.975 122.727 133.729 121.303 135.429 118.905L148.323 100.723C150.559 97.5686 150.559 93.3405 148.323 90.1864L135.429 72.0045C133.729 69.6064 130.975 68.1818 128.041 68.1818L84.0658 68.1818L84.0658 54.5455L133.927 54.5455C138.934 54.5455 142.993 50.4755 142.993 45.4545L142.993 9.09091C142.993 4.07014 138.934 0 133.927 0L21.9592 0ZM125.702 109.091L20.6058 109.091L20.6058 81.8182L125.702 81.8182L135.372 95.4545L125.702 109.091Z"Simplify Path
.simplify()
Set the path to the same non-overlapping contour as the original path area, which means that it can also remove overlapping paths.
SVG with overlapping paths (Left)
const path =
'M2.933,89.89 L89.005,3.818 Q90.412,2.411 92.249,1.65 Q94.087,0.889 96.076,0.889 Q98.065,0.889 99.903,1.65 Q101.741,2.411 103.147,3.818 L189.22,89.89 Q190.626,91.296 191.387,93.134 Q192.148,94.972 192.148,96.961 Q192.148,98.95 191.387,100.788 Q190.626,102.625 189.219,104.032 Q187.813,105.439 185.975,106.2 Q184.138,106.961 182.148,106.961 Q180.159,106.961 178.322,106.2 Q176.484,105.439 175.077,104.032 L89.005,17.96 L96.076,10.889 L103.147,17.96 L17.075,104.032 Q15.668,105.439 13.831,106.2 Q11.993,106.961 10.004,106.961 Q8.015,106.961 6.177,106.2 Q4.339,105.439 2.933,104.032 Q1.526,102.625 0.765,100.788 Q0.004,98.95 0.004,96.961 Q0.004,94.972 0.765,93.134 Q1.526,91.296 2.933,89.89 Z'
path.simplify().toSVGString()
// => "M89.005 3.818L2.933 89.89Q1.526 91.296 0.765 93.134Q0.004 94.972 0.004 96.961Q0.004 98.95 0.765 100.788Q1.526 102.625 2.933 104.032Q4.339 105.439 6.177 106.2Q8.015 106.961 10.004 106.961Q11.993 106.961 13.831 106.2Q15.668 105.439 17.075 104.032L96.076 25.031L175.077 104.032Q176.484 105.439 178.322 106.2Q180.159 106.961 182.148 106.961Q184.138 106.961 185.975 106.2Q187.813 105.439 189.219 104.032Q190.626 102.625 191.387 100.788Q192.148 98.95 192.148 96.961Q192.148 94.972 191.387 93.134Q190.626 91.296 189.22 89.89L103.147 3.818Q101.741 2.411 99.903 1.65Q98.065 0.889 96.076 0.889Q94.087 0.889 92.249 1.65Q90.412 2.411 89.005 3.818Z"Lottie Animation
Render Lottie animations using Skia's Skottie module.
Load Animation
const { LottieAnimation } = require('@napi-rs/canvas')
// Load from file
const animation = LottieAnimation.loadFromFile('animation.json')
// Load from JSON string with resource path for external assets
const animation = LottieAnimation.loadFromData(jsonString, {
resourcePath: '/path/to/assets',
})Animation Properties
animation.duration // Total duration in seconds
animation.fps // Frames per second
animation.frames // Total frame count
animation.width // Animation width
animation.height // Animation height
animation.version // Lottie format versionPlayback Control
animation.seekFrame(30) // Seek to frame 30
animation.seek(1.5) // Seek to 1.5 secondsRender to Canvas
const { createCanvas, LottieAnimation } = require('@napi-rs/canvas')
const animation = LottieAnimation.loadFromFile('animation.json')
const canvas = createCanvas(animation.width, animation.height)
const ctx = canvas.getContext('2d')
// Render at original size
animation.render(ctx)
// Render with custom destination rect
animation.render(ctx, { x: 0, y: 0, width: 800, height: 600 })Supported Features
- Embedded images - Base64-encoded images (
data:image/png;base64,...) - Embedded fonts - Vector glyph paths for text rendering without system fonts
- External assets - Load images from
resourcePathdirectory - dotLottie format - Extract
.lottieZIP files at runtime (see example)
Example: Encode Lottie to Video
See example/lottie-to-video.ts for encoding Lottie animations to MP4 using @napi-rs/webcodecs.
import { createCanvas, LottieAnimation } from '@napi-rs/canvas'
import {
VideoEncoder,
VideoFrame,
Mp4Muxer,
type EncodedVideoChunk,
type EncodedVideoChunkMetadata,
} from '@napi-rs/webcodecs'
const animation = LottieAnimation.loadFromFile('animation.json')
const canvas = createCanvas(animation.width, animation.height)
const ctx = canvas.getContext('2d')
for (let frame = 0; frame < animation.frames; frame++) {
animation.seekFrame(frame)
ctx.fillStyle = '#ffffff'
ctx.fillRect(0, 0, canvas.width, canvas.height)
animation.render(ctx)
// Encode frame to video...
}Example
The tiger.json was serialized from gojs/samples/tiger
node example/anime-girl.js| SVG | PNG | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CC-BY-SA 3.0 by Niabot | CC-BY-SA 3.0 by Niabot |
Building
Build skia from source
You can build this project from source, the system requirements are here: https://skia.org/docs/user/build
# Clone the code:
$ git clone --recurse-submodules https://github.com/Brooooooklyn/canvas.git
$ cd canvas
# Build Skia:
$ node scripts/build-skia.js
# Install NPM packages, build the Node.js addon:
$ npm install -g yarn
$ yarn install --mode=skip-build # `canvas` (node-canvas) is a native module that only the node-canvas compat tests use and is hard to install, you can skip building it by specifying `--mode=skip-build`
$ sudo dnf install clang # https://fedora.pkgs.org/34/fedora-x86_64/clang-12.0.0-0.3.rc1.fc34.x86_64.rpm.html
$ yarn build
# All done! Run test cases or examples now:
$ yarn test
$ node example/tiger.jsPull pre-build skia binary from GitHub
You can pull skia pre-build binaries if you just care the Rust part:
# Clone the code:
$ git clone --recurse-submodules https://github.com/Brooooooklyn/canvas.git
$ cd canvas
# Download Skia binaries:
# It will pull the binaries match the git hash in `./skia` submodule
$ node scripts/release-skia-binary.mjs --download
# Install NPM packages, build the Node.js addon:
$ npm install -g yarn
$ yarn install --mode=skip-build
$ sudo dnf install clang # https://fedora.pkgs.org/34/fedora-x86_64/clang-12.0.0-0.3.rc1.fc34.x86_64.rpm.html
$ yarn build
# All done! Run test cases or examples now:
$ yarn test
$ node example/tiger.js