{"id":10620,"library":"chartjs-node-canvas","title":"Chart.js Node.js Canvas Renderer","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/SeanSobey/ChartjsNodeCanvas","tags":["javascript","typescript"],"install":[{"cmd":"npm install chartjs-node-canvas","lang":"bash","label":"npm"},{"cmd":"yarn add chartjs-node-canvas","lang":"bash","label":"yarn"},{"cmd":"pnpm add chartjs-node-canvas","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for chart rendering logic (v3.x or v4.x).","package":"chart.js","optional":false},{"reason":"Runtime dependency providing the headless Canvas API implementation.","package":"canvas","optional":false}],"imports":[{"note":"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.","wrong":"const { ChartJSNodeCanvas } = require('chartjs-node-canvas');","symbol":"ChartJSNodeCanvas","correct":"import { ChartJSNodeCanvas } from 'chartjs-node-canvas';"},{"note":"Type import for configuring the ChartJSNodeCanvas instance.","symbol":"ChartJSNodeCanvasOptions","correct":"import type { ChartJSNodeCanvasOptions } from 'chartjs-node-canvas';"},{"note":"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.","wrong":"import Chart from 'chart.js'; // Then try to use Chart.register()","symbol":"Chart.register","correct":"import { Chart, CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend } from 'chart.js';\nChart.register(CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend);"}],"quickstart":{"code":"import { ChartJSNodeCanvas } from 'chartjs-node-canvas';\nimport { Chart, CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend } from 'chart.js';\nimport { writeFile } from 'node:fs/promises';\n\n// Register Chart.js components (required since Chart.js v3)\nChart.register(CategoryScale, LinearScale, BarController, BarElement, Title, Tooltip, Legend);\n\nconst width = 800; // px\nconst height = 600; // px\nconst backgroundColour = '#ffffff'; // Optional, defaults to white\n\nconst chartJSNodeCanvas = new ChartJSNodeCanvas({\n  width,\n  height,\n  backgroundColour,\n  plugins: { // Optional, global Chart.js plugins\n    // id: 'customPlugin',\n    // beforeDraw: (chart) => { /* ... */ }\n  },\n  chartCallback: (ChartJS) => {\n    // This is a special hook to globally configure Chart.js (e.g., register custom fonts or plugins)\n    // ChartJS.defaults.font.family = '\"Custom Font\", sans-serif';\n  }\n});\n\nconst configuration = {\n  type: 'bar' as const,\n  data: {\n    labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],\n    datasets: [{\n      label: 'Dataset 1',\n      data: [65, 55, 80, 81, 56, 55, 40],\n      backgroundColor: 'rgba(75, 192, 192, 0.6)'\n    }, {\n      label: 'Dataset 2',\n      data: [28, 48, 40, 19, 86, 27, 90],\n      backgroundColor: 'rgba(153, 102, 255, 0.6)'\n    }]\n  },\n  options: {\n    scales: {\n      y: {\n        beginAtZero: true\n      }\n    },\n    plugins: {\n      title: {\n        display: true,\n        text: 'Chart.js Bar Chart Example'\n      }\n    }\n  }\n};\n\n(async () => {\n  try {\n    const buffer = await chartJSNodeCanvas.renderToBuffer(configuration);\n    await writeFile('./chart.png', buffer);\n    console.log('Chart saved to chart.png');\n  } catch (error) {\n    console.error('Error generating chart:', error);\n  }\n})();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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+.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: Canvas is not defined"},{"fix":"Import the specific chart components (e.g., `CategoryScale`, `LinearScale`, `BarController`) from `chart.js` and call `Chart.register()` with them before creating charts.","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.","error":"TypeError: Chart.register is not a function"},{"fix":"Run `npm install chartjs-node-canvas` to ensure the package is correctly installed.","cause":"The `chartjs-node-canvas` package was not found in your `node_modules` directory, likely due to an incomplete or failed `npm install`.","error":"Error: Cannot find module 'chartjs-node-canvas'"},{"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.","cause":"The Node.js process does not have the necessary write permissions to save the generated chart image to the specified output path.","error":"Error: EACCES: permission denied, open 'path/to/chart.png'"}],"ecosystem":"npm"}