Migrating to Version 4 of D3, part 2: Modules, Packages, and Plugins

In my last article on migrating to the new version of D3, I covered some of the changes that stood out to me as particularly useful. Now we’ll cover one of the biggest changes in D3: packages and npm. It’s now a modular library, designed to be easily extended with custom plugins.

To create data visualizations with the new version of D3, you don’t need to use npm or even know how to make a custom plugin. You can continue using the full standard build of D3.

However, if you want to take your skills to the next level and start building your own modules, or use only a subset of the d3 libraries on a project, or even overwrite existing modules in the D3 library, this article is for you.

In this article, I’m discussing some concepts for creating your own custom modules and packages for D3. If you’re ready to start coding, go ahead and jump to the tutorials on my github repo.


If you’ve developed data visualizations in previous versions of d3.js, you probably focused your efforts on using the library. If you did look at the source code, it was probably so you could figure out how it worked.

With this new version, you can do more than just look at the source code. You can extend and modify it. The whole library has been rebuilt, from the ground up, to make it easier to extend and modify. You can even pick and choose which modules to bundle with your own project.

The dev process is a little more complicated now, but it’s still manageable.

There are definitely two separate stages:

  1. plugin/source-code development, and
  2. visualization development.

Depending on the project, these stages can be tightly connected or completely separate.

Basic pattern to developing, building, and testing custom d3 plugins with npm

1. Get starter files/boiler-plate code

2. Edit/Write source code

3. Edit/Update Metadata for Building with npm (only edited when changing which resources to build)

4. Test/Build plugin with npm tools

in steps 1–4 we’re working with source code, in step 5 with built-library

5. Test/Use the newly built plugin in a browser with an html document.


Building a D3 Plugin

There’s a lot of boiler-plate needed for building a plugin with npm. Most of it can be ignored. When starting out, you can focus on just a few files.

Before building the plugin, you’ll need to tell npm what to build. This information is often referred to as “metadata”.

package.json

  • This file contains the information npm needs to build your plugin.
  • It’s at the root level of your project.

index.js

  • This file maps your source code to the main function calls from your plugin.
  • It is also at the root level of your project
index.js

Source code?

The source code for your plugin will be in the ‘src’ folder of your project

/src/foo.js file

This is the actual code that we might call with d3.foo() in a visualization project. ‘default’ is the ‘main’ function, and is mapped to the function name you defined in the index.js file.

Once you’re all set, you can run npm test to build your plugin. The build tools will follow the instructions in your index.js and package.json files, and create your plugin. After a successful build, the plugin file (d3.plugin-name.js) can be found in the project’s build folder.

To use your new plugin, you’ll copy the d3.plugin-name.js to another folder, where you’ll use it to build a data visualization. Just like you would with the whole d3.js library.

Your visualization’s html file might look something like this (if it was very minimal, and not very visual):

And in the browser, you would see that ‘42’ logged to the console.

Inspecting our console log output, in the browser console.

Start Coding!

There’s nothing like digging in and writing and testing code, to better understand how to build a d3 plugin (or anything coded). So go ahead and jump to the tutorials on my github repo.

Also, be sure to read Mike Bostock’s article on developing d3.js plugins: ‘Let’s Make a (D3) Plugin’ article.


Many thanks go to Robert Crocker and Steph Monette, who read through early drafts. They found bugs, suggested improvements, and provided perspectives I hadn’t considered.

I also want to thank members of the D3 community in the San Francisco Bay Area who read through and made excellent suggestions for improvement.