Server-side D3 Visualization

Common errors

• TypeError: d3n.createCanvas is not a function

  cause The `canvasModule` option was not provided to the `D3Node` constructor, or the `canvas` package is not installed.
  fix Install `canvas` (`npm install canvas`) and initialize `D3Node` with `new D3Node({ canvasModule: require('canvas') })`.

• ReferenceError: d3 is not defined

  cause Attempting to use the global `d3` object (e.g., `d3.scaleLinear()`) without properly accessing it from the `D3Node` instance or importing it directly.
  fix Access D3 methods via the D3Node instance: `const d3Local = d3n.d3; d3Local.scaleLinear()` or explicitly `import * as d3 from 'd3';` if using specific D3 modules outside of the D3Node context.

• Error: Node was not found

  cause This error often occurs in D3.js when trying to append elements to a non-existent or invalid DOM element. In `d3-node`, it might mean the `selector` or `container` options are misconfigured, or D3 is trying to operate on an element that hasn't been created or selected correctly within the virtual DOM.
  fix Ensure the `selector` matches an element in the `container` HTML string, and that you are appending to a valid D3 selection object obtained from `d3n.document.querySelector()` or `d3n.createSVG()`.

Warnings

• gotcha d3-node is explicitly tested on Node.js v16 and up. Using older Node.js versions might lead to unexpected behavior or compatibility issues with underlying D3.js or other dependencies.
  Fix: Ensure your Node.js environment is at least version 16.0.0. Consider using a Node Version Manager (nvm) to easily switch between versions.
• breaking When generating raster images (e.g., PNG), the `canvas` package must be installed separately as a peer dependency and passed to the D3Node constructor via the `canvasModule` option. It is not bundled directly with `d3-node`.
  Fix: Install `canvas` via `npm install canvas` or `yarn add canvas` and initialize D3Node with `{ canvasModule: require('canvas') }`.
• gotcha D3.js itself underwent significant breaking changes between v3 and v4 (and subsequent versions), including a modularized structure and changes to API calls (e.g., `d3.scale.linear()` became `d3.scaleLinear()`). If adapting older D3 code, you must port it to a modern D3.js API, which `d3-node` supports via its internal D3 instance.
  Fix: Refer to D3.js migration guides for specific changes from older versions (e.g., v3 to v4). Pay close attention to naming conventions, module imports, and the data join pattern (e.g., `selection.merge()` in v4+).

Install

• npm install d3-node npm
• yarn add d3-node yarn
• pnpm add d3-node pnpm

Imports

• D3Node
  wrong:

  const D3Node = require('d3-node')

  correct:

  import { D3Node } from 'd3-node'

  While CommonJS `require` is supported, ESM `import` is the recommended and modern approach for Node.js v16 and up. The library internally bundles D3, so you typically interact with D3 via `d3n.d3`.
• D3 selection object

  const d3 = d3n.d3

  After initializing `D3Node`, access the D3 selection object through the `d3` property of the `D3Node` instance.
• SVG string output

  d3n.svgString()

  Used to retrieve the generated SVG as a string. For full HTML output including the container, use `d3n.html()`.

Quickstart

This quickstart demonstrates how to create a simple bar chart SVG using d3-node, including setting up axes and styling, and then saving the output to a file. It shows integration with both d3-node's D3 instance and explicit D3 imports for scales.

import { D3Node } from 'd3-node';
import * as d3 from 'd3'; // Import D3 for specific utilities like scaleLinear
import fs from 'fs';

const options = { 
  selector: '#chart', 
  container: '<div id="container"><div id="chart"></div></div>', 
  styles: '.bar { fill: steelblue; } .axis path, .axis line { fill: none; stroke: #000; shape-rendering: crispEdges; }'
};

const d3n = new D3Node(options);
const d3Local = d3n.d3; // Get the D3 instance associated with D3Node

const width = 400;
const height = 200;
const margin = { top: 20, right: 20, bottom: 30, left: 40 };

const svg = d3n.createSVG(width, height);

const data = [10, 20, 40, 60, 80];

const xScale = d3.scaleBand()
  .range([margin.left, width - margin.right])
  .padding(0.1)
  .domain(data.map((d, i) => i));

const yScale = d3.scaleLinear()
  .range([height - margin.bottom, margin.top])
  .domain([0, d3.max(data)]);

svg.append('g')
  .attr('fill', 'steelblue')
  .selectAll('rect')
  .data(data)
  .join('rect')
    .attr('class', 'bar')
    .attr('x', (d, i) => xScale(i))
    .attr('y', d => yScale(d))
    .attr('height', d => yScale(0) - yScale(d))
    .attr('width', xScale.bandwidth());

// Add X axis
svg.append('g')
  .attr('class', 'axis x-axis')
  .attr('transform', `translate(0,${height - margin.bottom})`)
  .call(d3.axisBottom(xScale).tickFormat(i => `Item ${i + 1}`));

// Add Y axis
svg.append('g')
  .attr('class', 'axis y-axis')
  .attr('transform', `translate(${margin.left},0)`)
  .call(d3.axisLeft(yScale));

const svgOutput = d3n.svgString();
fs.writeFileSync('output.svg', svgOutput);
console.log('SVG written to output.svg');

// For canvas output (requires 'canvas' package):
// import Canvas from 'canvas';
// const d3nCanvas = new D3Node({ canvasModule: Canvas });
// const canvas = d3nCanvas.createCanvas(width, height);
// const context = canvas.getContext('2d');
// // ... draw on context with D3-Canvas specific methods ...
// canvas.createPNGStream().pipe(fs.createWriteStream('output.png'));