chartjs-node-canvas

A Node JS renderer for Chart.js using canvas.

Provides and alternative to chartjs-node that does not require jsdom (or the global variables that this requires) and allows chartJS as a peer dependency, so you can manage its version yourself.

Installation
Node JS version
Features
Limitations
API
Usage
Known Issues

Installation

npm i chartjs-node-canvas chart.js

Node JS version

This is limited by the upstream dependency canvas.

See the GitHub Actions yml section for the current supported Node version(s). You will need to do a npm rebuild to rebuild the canvas binaries.

Charts.JS version

Currently supports 3.x.x. You are given the ability to maintain the version yourself via peer dependency, but be aware that going above the specified version might result in errors.

Features

Supports all Chart JS features and charts.
No heavy DOM virtualization libraries, thanks to a pull request to chart.js allowing it to run natively on node, requiring only a Canvas API.
Chart JS is a peer dependency, so you can bump and manage it yourself.
Provides a callback with the global ChartJS variable, so you can use the Global Configuration.
Uses (similar to) fresh-require for each instance of ChartJSNodeCanvas, so you can mutate the ChartJS global variable separately within each instance.
Support for custom fonts.

Limitations

Animations

Chart animation (and responsive resize) is disabled by this library. This is necessary since the animation API's required are not available in Node JS/canvas-node (this is not a browser environment after all).

This is the same as:

Chart.defaults.animation = false;
Chart.defaults.responsive = false;

SVG and PDF

For some unknown reason canvas requires use of the sync API's to use SVG's or PDF's. This libraries which support these are:

renderToBufferSync ('application/pdf' | 'image/svg+xml')
renderToStream ('application/pdf')

You also need to set the canvas type when you initialize the ChartJSNodeCanvas instance like the following:

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

const chartJSNodeCanvas = new ChartJSNodeCanvas({ type: 'svg', width: 800, height: 600 });

API

See the API docs.

Usage

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

const width = 400; //px
const height = 400; //px
const backgroundColour = 'white'; // Uses https://www.w3schools.com/tags/canvas_fillstyle.asp
const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, backgroundColour});

(async () => {
    const configuration = {
        ... // See https://www.chartjs.org/docs/latest/configuration
    };
    const image = await chartJSNodeCanvas.renderToBuffer(configuration);
    const dataUrl = await chartJSNodeCanvas.renderToDataURL(configuration);
    const stream = chartJSNodeCanvas.renderToStream(configuration);
})();

Also see the example and the generated image.

Memory Management

Every instance of ChartJSNodeCanvas creates its own canvas. To ensure efficient memory and GC use make sure your implementation creates as few instances as possible and reuses them:

// Re-use one service, or as many as you need for different canvas size requirements
const smallChartJSNodeCanvas = new ChartJSNodeCanvas({ width: 400, height: 400 });
const bigCChartJSNodeCanvas = new ChartJSNodeCanvas({ width: 2000, height: 2000 });

// Expose just the 'render' methods to downstream code so they don't have to worry about life-cycle management.
exports = {
    renderSmallChart: (configuration) => smallChartJSNodeCanvas.renderToBuffer(configuration),
    renderBigChart: (configuration) => bigCChartJSNodeCanvas.renderToBuffer(configuration)
};

Custom Charts

Just use the ChartJS reference in the callback:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, chartCallback: (ChartJS) => {
    // New chart type example: https://www.chartjs.org/docs/latest/developers/charts.html
    class MyType extends Chart.DatasetController {

    }

    Chart.register(MyType);
    }
});

Global Config

Just use the ChartJS reference in the callback:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, chartCallback: (ChartJS) => {
    // Global config example: https://www.chartjs.org/docs/latest/configuration/
    ChartJS.defaults.elements.line.borderWidth = 2;
} });

Custom Fonts

Just use the registerFont method:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, chartCallback: (ChartJS) => {
    // Just example usage
    ChartJS.global.defaultFontFamily = 'VTKS UNAMOUR';
} });
// Register before rendering any charts
chartJSNodeCanvas.registerFont('./testData/VTKS UNAMOUR.ttf', { family: 'VTKS UNAMOUR' });

See the node-canvas docs and the chart js docs.

Background color

Due to the many issues and question this includes a convenience plugin to fill the otherwise transparent background. It uses the fillStyle canvas API;

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, backgroundColour: 'purple' });

Loading plugins

This library is designed to make loading plugins as simple as possible. For legacy plugins, you should just be able to add the module name to the appropriate array option and the library handles the rest.

The Chart.JS plugin API has changed over time and this requires compatibility options for the different ways plugins have been historically loaded. ChartJS Node Canvas has a plugin option with specifiers for the different ways supported plugin loading methods are handled. If you are not sure about your plugin, just try the different ones until your plugin loads:

Newer plugins

Let ChartJSNodeCanvas manage the lifecycle of the plugin itself, each instance will have a separate instance of the plugin:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    modern: ['chartjs-plugin-annotation']
} });

You want to share the plugin instance, this may cause unwanted issues, use at own risk:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    modern: [require('chartjs-plugin-annotation')]
} });

Older plugins

Plugin that expects a global Chart variable.

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    requireChartJSLegacy: ['<some plugin>']
}});

Plugins that require ChartJS themselves.

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    globalVariableLegacy: ['chartjs-plugin-crosshair']
} });

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    requireLegacy: ['chartjs-plugin-datalabels']
} });

These approaches can be combined also:

const chartJSNodeCanvas = new ChartJSNodeCanvas({ width, height, plugins: {
    modern: ['chartjs-plugin-annotation'],
    requireLegacy: ['chartjs-plugin-datalabels']
} });

See the tests for some examples.

Known Issues

There is a problem with persisting config objects between render calls, see this issue for details and workarounds.

souhe / chartjsnodecanvas Goto Github PK