d3-pre

    1.3.0 • Public • Published

    d3-pre

    A JavaScript library that pre-renders d3 visualizations into inline SVG elements, to reduce perceived page-load time and cut down on unwanted paint flashes.

    The pre-rendering tool uses a headless browser to turn d3 code into its resulting SVG, and inserts the markup into your HTML. Then, the d3-pre JavaScript library overrides d3.append to check if a pre-rendered DOM node already exists before creating a new one. This approach allows you to use pre-rendered SVG without changing your visualization code.

    See an example of the speed benefits of using inline SVG over SVG generated in the client by refreshing this page without pre-rendering and with pre-rendering.

    Examples

    In the wild

    Installation

    npm install --save d3-pre
    

    Usage

    There are two things that you need to do to use this library:

    1. Include d3-pre in your javascript

    var d3 = require('d3');
     
    // Require the library and give it a reference to d3
    var Prerender = require('d3-pre');
    var prerender = Prerender(d3);
     
     
    // Then, when you start drawing SVG, call `prerender.start()`.
    // This modifies some d3 functions to make it aware
    // of the pre-rendered SVGs.
    prerender.start();
     
    /*
     * Existing d3 code goes here
     * d3.select('body')
     *   .append('svg')
     *      .data(data)
     *   .enter()
     *      .append('rect')
     *      .on('click', clickhandler)
     *      etc. etc.
    */
     
    // If you ever want to go back to the unmodified d3,
    // just call `prerender.stop()`.
    // This is optional and usually not necessary.
    prerender.stop();
     

    2. Pass your HTML through the pre-rendering tool.

    This can be done via a build task (like gulp), or on the command line. To provide control over which DOM modifications are saved back to the HTML file, you can add the following data-attributes in the HTML:

    • data-prerender-ignore: Any modifications that happen inside a node with this attribute will be ignored.
    • data-prerender-only: Only modifications inside of this node are saved.
    • data-prerender-minify: Any SVG with this attribute will automatically be passed through an SVG minification tool.

    Command line example

    Install the command line tool:

    $ npm install -g d3-pre-cli
    

    Run the d3-pre command on an HTML file:

    $ d3-pre ./path/to/index.html
    

    This command will open the index.html file in a headless browser, running any JavaScript included on the page. Any modifications that the JavaScript makes to the DOM are saved back to the HTML file.

    Gulp example

    Install the gulp plugin:

    $ npm install gulp-d3-pre
    

    Create a gulp task:

    var gulp = require('gulp');
    var d3Pre = require('gulp-d3-pre');
     
     
    gulp.task('prerender-svgs', function() {
      gulp.src('./public/index.html')
        .pipe(d3Pre(options))
        .pipe(gulp.dest('./public/'));
    })

    This task will open the index.html file in a headless browser, running any JavaScript included on the page. Any modifications that the JavaScript makes to the DOM are saved back to the HTML file. The following options may be passed to the gulp plugin:

    • preprocessHTML - A function to run before running the HTML through the pre-renderer. Takes a string as input and expects a string as output.
    • postprocessHTML - A function to run after running the HTML through the pre-renderer. Takes a string as input and expects a string as output.

    Advanced usage

    Both of the above modules are thin wrappers around d3-pre-renderer. If you require more fine-grained control of when and where the pre-rendering step takes place, use d3-pre-renderer directly.

    Release Notes

    v1.3.0

    • Adds support for d3 v4.

    Contributors

    License

    MIT

    Keywords

    none

    Install

    npm i d3-pre

    DownloadsWeekly Downloads

    4

    Version

    1.3.0

    License

    MIT

    Last publish

    Collaborators

    • simranparwani
    • bycoffe
    • jayb
    • fivethirtyeight-bot
    • onyxfish
    • ryanabest
    • wiederkehra
    • elena.mejia