QuickChart JavaScript Client

Common errors

• TypeError: QuickChartClient is not a constructor

  cause Attempting to use the old class name `QuickChartClient` after upgrading to `quickchart-js` v2.0.0 or later.
  fix Change `new QuickChartClient()` to `new QuickChart()`.

• Error: ENOSPC: no space left on device, write

  cause The system lacks sufficient disk space to write the chart image to a file using `toFile()`.
  fix Free up disk space or choose a different output location with enough available storage.

• SyntaxError: Unexpected token 'function'

  cause Passing a Chart.js configuration object directly to `setConfig()` that contains JavaScript functions (e.g., in `options.scales.yAxes.ticks.callback`) without stringifying it.
  fix Stringify your chart configuration object if it contains JavaScript functions: `myChart.setConfig(JSON.stringify(myChartConfigObject));`

Warnings

• breaking Version 3.0.0 dropped support for Node.js 12. Ensure your environment runs Node.js 14 or higher when upgrading to `quickchart-js` v3.x.
  Fix: Upgrade your Node.js runtime to version 14 or newer.
• breaking In version 2.0.0, the main class name was changed from `QuickChartClient` to `QuickChart`. Older code using `new QuickChartClient()` will break.
  Fix: Update your imports and instantiations from `QuickChartClient` to `QuickChart`.
• gotcha Short URLs generated by `getShortUrl()` for free tier users expire after a few days. For persistent short URLs, a QuickChart.io subscription is required.
  Fix: For long-term storage or high-traffic applications, consider a QuickChart.io subscription or use `getUrl()` for non-expiring direct URLs.
• gotcha When using Chart.js functions (e.g., custom callbacks for tooltips or axis labels) within your chart configuration, the `setConfig` method expects the configuration to be a string, not a plain JavaScript object. The library internally uses `javascript-stringify` to handle this.
  Fix: If your chart configuration includes JavaScript functions, ensure you pass the config as a JSON string to `setConfig()`: `myChart.setConfig(JSON.stringify({ /* config with functions */ }));`
• gotcha The free (community) tier of QuickChart.io has limitations on certain Chart.js features and plugins due to compute restrictions. Access to the global `Chart` object and some advanced plugin properties might be restricted.
  Fix: If encountering issues with advanced Chart.js features or custom plugins, consider upgrading to a QuickChart.io subscriber plan or self-hosting the QuickChart API for unrestricted access. Refer to the QuickChart documentation for specific limitations.

Install

• npm install quickchart-js npm
• yarn add quickchart-js yarn
• pnpm add quickchart-js pnpm

Imports

• QuickChart
  wrong:

  const QuickChart = require('quickchart-js');

  correct:

  import { QuickChart } from 'quickchart-js';

  While CommonJS `require` works, ESM `import` is the recommended pattern in modern JavaScript and TypeScript projects. The package provides both CommonJS (`.cjs.js`) and ESM (`.mjs`) builds.
• QuickChart
  wrong:

  new QuickChart({ apiKey: '...', accountId: '...' });

  correct:

  new QuickChart(apiKey, accountId);

  The constructor directly accepts `apiKey` and `accountId` as positional arguments, not an options object. Omit arguments for the free community version.
• QuickChart.getGradientFillHelper
  wrong:

  myChart.getGradientFillHelper(...);

  correct:

  QuickChart.getGradientFillHelper('horizontal', ['red', 'green']);

  `getGradientFillHelper` is a static method on the `QuickChart` class, not an instance method. It's used for advanced Chart.js styling.

Quickstart

This quickstart demonstrates how to configure a Chart.js bar chart, customize its properties, retrieve both long and short URLs, and save the generated image to a local file.

import { QuickChart } from 'quickchart-js';
import * as fs from 'fs/promises';

const myChart = new QuickChart();
myChart.setConfig({
  type: 'bar',
  data: {
    labels: ['January', 'February', 'March', 'April', 'May'],
    datasets: [
      { label: 'Dogs', data: [50, 60, 70, 180, 190] },
      { label: 'Cats', data: [100, 200, 300, 400, 500] }
    ],
  },
  options: {
    plugins: {
      legend: { position: 'top' },
      title: { display: true, text: 'Monthly Pet Counts' },
    },
  },
});

myChart.setWidth(800);
myChart.setHeight(400);
myChart.setFormat('png');
myChart.setBackgroundColor('#f8f8f8');

async function generateCharts() {
  // Get the direct URL
  console.log('Direct Chart URL:', myChart.getUrl());

  // Get a short, fixed-length URL (requires network request)
  try {
    const shortUrl = await myChart.getShortUrl();
    console.log('Short Chart URL:', shortUrl);
  } catch (error) {
    console.error('Failed to get short URL:', error);
  }

  // Write the chart to a file
  const filePath = './mychart.png';
  try {
    await myChart.toFile(filePath);
    console.log(`Chart saved to ${filePath}`);
  } catch (error) {
    console.error('Failed to save chart to file:', error);
  }
}

generateCharts();