Registry / web-framework / chartjs-node-canvas

chartjs-node-canvas

library5.0.0jsnpmunverified

chartjs-node-canvas is a Node.js library that enables server-side rendering of Chart.js charts into static image files (PNG, JPEG). It achieves this by utilizing the `canvas` package, which provides a Canvas API implementation compatible with Node.js environments, bypassing browser-specific rendering requirements. The current stable version is 5.0.0, which maintains compatibility with Chart.js v3.x and v4.x. While there isn't a strict, rapid release cadence, the project is actively maintained, with regular updates for dependency bumps and Node.js version support. Its primary differentiator is providing a reliable, performant way to generate Chart.js images outside of a browser, essential for tasks like generating reports, social media share images, or email attachments from server-side applications. It integrates directly with Chart.js as a peer dependency, requiring Chart.js itself to be installed separately, and allowing developers to manage its version.

web-framework data serialization

npm install chartjs-node-canvas

github ↗package ↗

INSTALL

IMPORT

SIG · CHARTJS-NODE-CANVA

chartjs-node-canvas

web-frameworkjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ChartJSNodeCanvas

✓ import { ChartJSNodeCanvas } from 'chartjs-node-canvas';

✗ const { ChartJSNodeCanvas } = require('chartjs-node-canvas');

While the library supports CommonJS 'require' (as shown in older examples), modern Node.js applications and TypeScript generally prefer ESM 'import' syntax. The library ships with types.

ChartJSNodeCanvasOptions

✓ import type { ChartJSNodeCanvasOptions } from 'chartjs-node-canvas';

Type import for configuring the ChartJSNodeCanvas instance.

Chart.register

✓ import { Chart, CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend } from 'chart.js'; Chart.register(CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend);

✗ import Chart from 'chart.js'; // Then try to use Chart.register()

Since Chart.js v3, components must be explicitly imported and registered for tree-shaking. The global 'Chart' object no longer includes all components by default. chartjs-node-canvas works with this pattern.

Demonstrates how to create an instance of `ChartJSNodeCanvas`, register necessary Chart.js components, define chart configuration, render it to a PNG buffer, and save it to a file on disk. This example shows a basic bar chart.

import { ChartJSNodeCanvas } from 'chartjs-node-canvas'; import { Chart, CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend } from 'chart.js'; import { writeFile } from 'node:fs/promises'; // Register Chart.js components (required since Chart.js v3) Chart.register(CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend); const width = 800; // px const height = 600; // px const backgroundColour = '#ffffff'; // Optional, defaults to white const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, backgroundColour, plugins: { // Optional, global Chart.js plugins // id: 'customPlugin', // beforeDraw: (chart) => { /* ... */ } }, chartCallback: (ChartJS) => { // This is a special hook to globally configure Chart.js (e.g., register custom fonts or plugins) // ChartJS.defaults.font.family = '"Custom Font", sans-serif'; } }); const configuration = { type: 'bar' as const, data: { labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'], datasets: [{ label: 'Dataset 1', data: [65, 55, 80, 81, 56, 55, 40], backgroundColor: 'rgba(75, 192, 192, 0.6)' }, { label: 'Dataset 2', data: [28, 48, 40, 19, 86, 27, 90], backgroundColor: 'rgba(153, 102, 255, 0.6)' }] }, options: { scales: { y: { beginAtZero: true } }, plugins: { title: { display: true, text: 'Chart.js Bar Chart Example' } } } }; (async () => { try { const buffer = await chartJSNodeCanvas.renderToBuffer(configuration); await writeFile('./chart.png', buffer); console.log('Chart saved to chart.png'); } catch (error) { console.error('Error generating chart:', error); } })();

Debug

Known issues

breakingVersion 4.0.0 migrated to support Chart.js v3.x.x, dropping support for Chart.js v2.x.x and removing older APIs. This requires updating chart configurations and explicitly registering Chart.js components (e.g., scales, controllers, elements) due to Chart.js's tree-shaking architecture in v3+.

fix

Ensure your `chart.js` dependency is `^3.0.0` or `^4.0.0`. Explicitly import and `Chart.register()` all necessary components (e.g., `CategoryScale`, `LinearScale`, `BarController`) from `chart.js` before rendering any charts.

affects: >=4.0.0

breakingVersion 2.0.0 replaced the deprecated `canvas-prebuilt` dependency with the standard `canvas` package. While `canvas` now typically includes prebuilt binaries, users previously managing `canvas-prebuilt` might need to adjust their dependency management or perform `npm rebuild` if encountering native module issues.

fix

Ensure `canvas` is correctly installed and built for your environment. If issues persist, try running `npm install canvas --build-from-source` or `npm rebuild` to ensure native modules are compiled correctly for your Node.js version.

affects: >=2.0.0

gotchaChart animations and responsive resizing are disabled by `chartjs-node-canvas` because the necessary animation and browser-specific resize APIs are not available in a Node.js/canvas environment.

fix

This is intended behavior for server-side rendering. Do not rely on animation or client-side responsiveness in charts generated with this library. Ensure your chart configuration is static.

affects: >=2.0.0

gotchaCustom fonts need to be registered with the `ChartJSNodeCanvas` instance via `registerFont` if you intend to use fonts other than the system defaults or Chart.js's fallback fonts, especially in headless environments.

fix

Use `chartJSNodeCanvas.registerFont('./path/to/your/font.ttf', { family: 'Your Font Name' });` before rendering charts. Then specify `font.family` in your Chart.js options.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Canvas is not defined

The native `canvas` dependency (which `chartjs-node-canvas` relies on) is either not installed, or its native binaries failed to compile for your specific Node.js version and operating system.

fix

Ensure `canvas` is installed alongside `chartjs-node-canvas` (e.g., `npm install chartjs-node-canvas canvas chart.js`). If the issue persists, try `npm rebuild` or `npm install canvas --build-from-source`.

TypeError: Chart.register is not a function

This error typically occurs when using Chart.js v3+ without explicitly importing and registering the required components. In Chart.js v3 and later, the global `Chart` object does not automatically include all chart types and scales.

fix

Import the specific chart components (e.g., `CategoryScale`, `LinearScale`, `BarController`) from `chart.js` and call `Chart.register()` with them before creating charts.

Error: Cannot find module 'chartjs-node-canvas'

The `chartjs-node-canvas` package was not found in your `node_modules` directory, likely due to an incomplete or failed `npm install`.

fix

Run `npm install chartjs-node-canvas` to ensure the package is correctly installed.

Error: EACCES: permission denied, open 'path/to/chart.png'

The Node.js process does not have the necessary write permissions to save the generated chart image to the specified output path.

fix

Ensure the directory where you are attempting to save the image exists and that the user running the Node.js process has write permissions for that directory.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

chart.jsrequiredPeer dependency required for chart rendering logic (v3.x or v4.x).

canvasrequiredRuntime dependency providing the headless Canvas API implementation.

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/SeanSobey/ChartjsNodeCanvas ↗

packagehttps://www.npmjs.com/package/chartjs-node-canvas ↗