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

> A server-side Canvas implementation for Node.js powered by Cairo, enabling image generation without a browser.

## Install

Save as a script file and run:

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

## Quick Use
```bash
npm install canvas
```
```js
import { createCanvas } from 'canvas';
const canvas = createCanvas(200, 200);
const ctx = canvas.getContext('2d');
ctx.fillStyle = '#09f';
ctx.fillRect(10, 10, 180, 180);
const buf = canvas.toBuffer('image/png');
// buf is a PNG image buffer ready to write or send
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-26b53af3
Author: Script Depot