The Problem
Building interactive data visualizations for the web typically means choosing between low-level graphics APIs (verbose, error-prone) and high-level chart libraries (inflexible, hard to customize). Teams that need custom, bespoke visualizations—think newsrooms, data journalism teams, or analytics platforms—often end up fighting the abstraction layer or writing hundreds of lines of boilerplate.
What This Does
This is D3.js, the foundational JavaScript library for data-driven document manipulation. It provides a modular set of utilities for binding data to DOM elements, computing scales and layouts, and generating SVG/Canvas shapes. The repo is a monorepo-style distribution: src/index.js re-exports the full public API, while docs/ contains the complete reference documentation for every module—docs/d3-array/, docs/d3-shape/, docs/d3-force/, etc.
The project is documentation-heavy (154 docs files, 119 Markdown files) with a VitePress-based site (docs/.vitepress/). The actual library code lives in the individual d3- packages on npm; this repo is the umbrella that ties them together. The bundle.js file indicates a pre-built UMD bundle for direct browser use.
How To Use It
Setup: This is a source repo, not a typical application. No build step is required for end users—D3 is consumed via npm (npm install d3) or a CDN <script> tag pointing at bundle.js.
Configuration: None. D3 has no global config, environment variables, or runtime settings. You import what you need and use it.
Running the docs locally (from package.json and the VitePress config):
yarn install yarn docs:dev
The docs site entry point is docs/.vitepress/config.ts, with custom components in docs/.vitepress/theme/ and docs/components/. Testing is done via test/d3-test.js and test/docs-test.js (run with yarn test).
Real-World Use
A typical workflow: fetch CSV data, parse it, compute scales, and render SVG elements.
import { csv, scaleLinear, max, select } from "d3";
const data = await csv("data.csv"); const x = scaleLinear().domain([0, max(data, d => d.value)]).range([0, 500]);
select("svg") .selectAll("rect") .data(data) .join("rect") .attr("width", d => x(d.value)) .attr("height", 20);
This pattern—data join, scales, and SVG generation—powers everything from simple bar charts to the interactive force-directed graphs and geographic projections documented in docs/d3-force/ and docs/d3-geo/.
Code Health & Issues
Low - No library source code in this repo: src/index.js is a re-export stub. The actual implementations live in separate d3- packages. Reviewing this repo alone tells you little about code quality. Low - Documentation drift risk: With 150+ doc files and a versioned API (CHANGES.md), keeping docs in sync with the 30+ sub-packages is a maintenance burden. The test/docs-test.js file likely checks this, but it's a constant effort. Low - No CI for library code: .github/workflows/test.yml exists, but given the repo structure, it primarily tests docs and the bundle, not the library internals.
The repo is clean: tests, CI, license, lockfile, and linting config (.eslintrc.json) are all present. The prebuild.sh and rollup.config.js indicate a proper build pipeline for generating bundle.js.
The Bottom Line
This is the canonical source for D3's documentation and distribution, not the library's implementation. For end users, install d3 from npm or use a CDN. The value here is the excellent, versioned reference documentation—useful for any team building custom data visualizations. The steep learning curve is real, but the flexibility is unmatched.