This document provides a comprehensive overview of the D3.js codebase architecture, focusing on how the main d3 package functions as a module aggregator and distribution system. It covers the modular design philosophy, build pipeline, testing framework, and documentation infrastructure that enables D3's ecosystem of 30+ independent visualization modules.
For detailed information about specific D3 modules and their APIs, see Module Documentation. For the complete version history and breaking changes across major releases, see Version History and Evolution.
D3 (Data-Driven Documents) is a JavaScript library for data visualization that operates as a collection of independent, composable modules rather than a monolithic framework. The main d3 package serves purely as a convenience aggregator that bundles 30+ specialized modules into a unified API.
D3 Module Aggregation Architecture
Sources: package.json37-67 src/index.js
D3's architecture is fundamentally modular, with each module serving a specific purpose in the data visualization pipeline. The main package contains no visualization logic itself—it exists solely to re-export functionality from its dependencies.
| Module Category | Example Modules | Purpose |
|---|---|---|
| Data Processing | d3-array, d3-dsv | Array utilities, CSV/TSV parsing |
| DOM Manipulation | d3-selection, d3-transition | Element selection, animations |
| Scales & Mapping | d3-scale, d3-time | Data-to-visual mapping |
| Shape Generation | d3-shape, d3-path | SVG path generation |
| Interaction | d3-drag, d3-zoom, d3-brush | User input handling |
| Layout & Hierarchy | d3-hierarchy, d3-force | Tree/network layouts |
Build and Testing Pipeline
Sources: rollup.config.js14-65 test/d3-test.js10-19 package.json81-87
The main D3 package uses semantic versioning and manages dependencies on 30 independent modules, each with their own version ranges. This allows individual modules to evolve independently while maintaining a stable aggregated interface.
Dependency and Export Management
Sources: package.json37-67 test/d3-test.js10-19
D3 uses Rollup to create multiple distribution formats from a single source. The build process aggregates all module exports and creates optimized bundles for different consumption patterns.
The rollup.config.js file defines three output formats:
dist/d3.js - Compatible with browsers, Node.js, and AMD loadersdist/d3.mjs - Native ES6 module formatdist/d3.min.js - Compressed for production useBuild System and Distribution Pipeline
Sources: rollup.config.js1-65 package.json24-36 bundle.js
The package.json defines multiple entry points for different module systems:
main: src/index.js (CommonJS/Node.js)module: src/index.js (ES modules)jsdelivr: dist/d3.min.js (CDN distribution)unpkg: dist/d3.min.js (CDN distribution)Sources: package.json29-36
D3 employs a comprehensive testing strategy that focuses on API surface verification and export completeness rather than functional testing (which occurs in individual modules).
The primary test suite in test/d3-test.js ensures that every export from every dependency module is properly re-exported by the main D3 package:
This approach guarantees API completeness without duplicating functional tests that exist in individual module repositories.
Sources: test/d3-test.js10-19
Sources: package.json75-82 test/.eslintrc.json1-12
D3 uses VitePress to generate its documentation website, with tight integration to Observable for live examples and community features.
Documentation Architecture
The documentation system serves multiple purposes:
Sources: docs/.vitepress/ package.json85-87 prebuild.sh1-5
The D3 development workflow emphasizes automation and quality gates:
| Script | Purpose | Implementation |
|---|---|---|
test | Run tests and linting | mocha 'test/**/*-test.js' && eslint src test |
prepublishOnly | Build distributions | rm -rf dist && rollup -c |
docs:dev | Development server | VitePress with experimental network imports |
docs:build | Production build | Asset prebuild + VitePress build |
Sources: package.json81-87
d3/
├── src/index.js # Main module entry point
├── bundle.js # Build system entry point
├── package.json # Package configuration & dependencies
├── rollup.config.js # Build configuration
├── test/
│ ├── d3-test.js # Export verification tests
│ └── docs-test.js # Documentation link validation
├── docs/ # VitePress documentation
│ ├── .vitepress/ # Site configuration
│ └── **/*.md # Documentation pages
└── dist/ # Generated distribution files
├── d3.js # UMD bundle
├── d3.mjs # ES module bundle
└── d3.min.js # Minified UMD bundle
The codebase maintains clear separation between:
src/dist/docs/test/Sources: package.json24-35 .gitignore1-10
Refresh this wiki