node-canvas — Cairo-Backed Canvas for Node.js

Introduction

node-canvas is a Cairo-backed implementation of the HTML5 Canvas API for Node.js. It allows server-side generation of images, charts, thumbnails, and other graphics using the same drawing API available in web browsers. Originally created by TJ Holowaychuk and maintained by Automattic, it is widely used for generating Open Graph images, PDF content, and automated visual assets.

What node-canvas Does

• Implements the HTML5 Canvas 2D API on the server side
• Generates PNG, JPEG, and PDF output from canvas drawings
• Supports custom fonts loaded from file paths
• Provides image loading from buffers, files, and URLs
• Enables SVG path rendering and text measurement

Architecture Overview

node-canvas is a native Node.js addon written in C++ that binds to the Cairo 2D graphics library. Cairo handles rasterization, font rendering (via FreeType and Fontconfig), and output to multiple backends (image surfaces for PNG/JPEG, PDF surfaces for vector output). The JavaScript API mirrors the browser CanvasRenderingContext2D interface, so code written for the browser largely works unchanged on the server.

Self-Hosting & Configuration

• Install via npm: npm install canvas (requires Cairo and Pango system libraries)
• On Ubuntu/Debian: sudo apt install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
• On macOS: brew install pkg-config cairo pango libpng jpeg giflib librsvg
• Register custom fonts with registerFont('./font.ttf', { family: 'MyFont' }) before creating a canvas
• Use canvas.createPDFStream() for streaming PDF output

Key Features

• Near-complete HTML5 Canvas 2D context compatibility
• PNG, JPEG, and PDF output backends
• Custom font registration for server-side text rendering
• Image compositing and blend modes
• SVG path data support via Path2D

Comparison with Similar Tools

• sharp — image processing (resize, crop, convert); node-canvas is for drawing and generating images from scratch
• Puppeteer/Playwright — render full web pages to images; node-canvas renders canvas drawings without a browser
• Skia (via skia-canvas) — alternative graphics backend; node-canvas uses Cairo and has broader adoption
• jimp — pure JavaScript image manipulation; node-canvas uses native Cairo for better performance

FAQ

Q: Do I need system libraries to install node-canvas? A: Yes. Cairo, Pango, and related development headers must be installed. Prebuilt binaries are available for common platforms.

Q: Can I use web fonts? A: Use registerFont() to load TTF or OTF font files before creating your canvas. Web font URLs are not directly supported.

Q: Does node-canvas support WebGL? A: No. It implements the 2D rendering context only. For 3D rendering on the server, consider headless-gl or Puppeteer.

Q: Can I generate PDFs with node-canvas? A: Yes. Create a canvas with createCanvas(width, height, 'pdf') and use canvas.toBuffer() or createPDFStream().

Sources

• https://github.com/Automattic/node-canvas
• https://github.com/Automattic/node-canvas/wiki