Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
D3Node
✓ import { D3Node } from 'd3-node'
✗ const D3Node = require('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()`.
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'));
Errors
Common errors & fixes
TypeError: d3n.createCanvas is not a function
The `canvasModule` option was not provided to the `D3Node` constructor, or the `canvas` package is not installed.
fixInstall `canvas` (`npm install canvas`) and initialize `D3Node` with `new D3Node({ canvasModule: require('canvas') })`. ReferenceError: d3 is not defined
Attempting to use the global `d3` object (e.g., `d3.scaleLinear()`) without properly accessing it from the `D3Node` instance or importing it directly.
fixAccess 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
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.
fixEnsure 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()`.
Audit
Dependencies
d3requiredCore D3.js library for data manipulation and visualization logic.
canvasoptionalRequired for generating raster images (PNG) from D3 visualizations on the server-side. Must be installed separately.