Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 44 ยท Getting Started

Setting Up D3: CDN, ES Modules and npm

Load D3.js with a script tag, as an ES module from a CDN or from npm, import only the modules you need, and set up a clean HTML page for your charts.

Before you draw anything you need D3 on the page. There are three common ways to get it: a classic <script> tag, an ES module import, and npm with a bundler. They all give you the same functions; they differ in how you name them. This lesson shows each one and helps you choose.

The script tag (global d3)

The simplest option is the pre-built bundle. It adds one global variable, d3, that holds every function.

HTML
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/d3.min.js"></script>
<script>
  console.log(d3.version);
</script>

Always pin an exact version ([email protected]) in the URL. An unpinned URL can change under you when a new release ships. The pre-built file contains all modules, so it is a good default for learning, demos and small pages. It is what this track uses in its live examples.

The global d3 object

ES modules from a CDN

Modern browsers load JavaScript modules natively. jsDelivr's +esm suffix serves an ES module build, so you can import D3 without installing anything:

HTML
<script type="module">
  import * as d3 from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";
  d3.select("body").append("p").text("Hello from a module");
</script>

Module scripts are deferred automatically, run in strict mode, and have their own scope, so d3 is not a global unless you assign it yourself. This style also lets you import individual parts.

Importing only what you need

Importing d3-selection and d3-scale separately keeps the download small. The names after import are the same as in the bundle, minus the d3. prefix.

npm and a bundler

For a real application, install D3 from npm and let a bundler (Vite, webpack, esbuild) pick what to ship:

Terminal
npm install d3
JavaScript
// A. everything under one name (the bundler tree-shakes unused code)
import * as d3 from "d3";

// B. only specific functions
import { select, selectAll } from "d3-selection";
import { scaleLinear } from "d3-scale";

Version 7 is published as ES modules. If a tool still expects CommonJS (older Jest setups, for example), see the Testing lesson in chapter 8: there is a standard configuration to handle that.

Do not mix both styles for the same module in one project. import * as d3 from "d3" plus import { select } from "d3-selection" can load two copies of d3-selection, and then instanceof checks and selection .call() helpers behave oddly. Pick one style per project.

Which one should you choose?

Situation Best choice
Learning, a quick prototype, a CodePen-style demo Script tag with the pre-built bundle
A small static page without a build step ES module from jsDelivr
A production app with React, Vue, Svelte or Angular npm + bundler, import only the modules you need
A notebook (Observable) d3 is already available

A clean starting page

Every example in this track follows the same skeleton. It has a container, an SVG with an explicit size, and a script that selects the SVG and draws.

A reusable starting template

Notice that the script comes after the element it uses. If a script runs before the DOM node exists, d3.select("#chart") returns an empty selection and everything after it silently does nothing. Put scripts at the end of <body>, use type="module" (deferred), or wait for DOMContentLoaded.

Debugging tips

  • Open the browser's dev tools and inspect the generated elements in the Elements panel. D3 creates real DOM nodes, so what you see there is what D3 made.
  • console.log(selection) prints the selection. Use selection.size() to see how many elements it holds and selection.nodes() to get the elements as an array.
  • A blank chart most often means: the script ran too early, a selector is wrong, an attribute is NaN, or the SVG has no width and height. Inspect the attributes to find which.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you pin the D3 version in a CDN URL?

    An exact version gives reproducible pages. Unpinned or range URLs may resolve to a newer release.
  2. 2. What is true about a <script type="module"> that imports D3?

    Modules are deferred, strict-mode and scoped. You get d3 by importing it, not as a global.
  3. 3. What commonly happens if your script runs before the target element exists?

    Selections tolerate missing elements, so mistakes are silent. Check selection.size() when something does not appear.
  4. 4. Why avoid importing both 'd3' and 'd3-selection' in the same project?

    Two copies of a module can break instanceof checks and shared state. Choose one import style per project.

Summary

  • Use the script tag bundle for demos, a CDN ES module for small pages, and npm with a bundler for apps.
  • Pin an exact version; import only the modules you need when bundle size matters.
  • Place scripts after the elements they select, and give SVGs an explicit size.
  • Inspect the DOM, selection.size() and selection.nodes() when a chart stays blank.

Next: SVG Fundamentals for D3