Chart.js Node.js Canvas Renderer

Common errors

• Error: Canvas is not defined

  cause 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

  cause 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'

  cause 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'

  cause 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.

Warnings

• breaking Version 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.
• breaking Version 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.
• gotcha Chart 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.
• gotcha Custom 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.

Install

• npm install chartjs-node-canvas npm
• yarn add chartjs-node-canvas yarn
• pnpm add chartjs-node-canvas pnpm

Imports

• ChartJSNodeCanvas
  wrong:

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

  correct:

  import { ChartJSNodeCanvas } from '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
  wrong:

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

  correct:

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

  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.

Quickstart

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);
  }
})();