d3-no-dom

Fully used3.jsin environments without DOM, such asCloudflare WorkersorVercel Functions

Features

• Simple API with maximum extensibility.
• Support for asynchronous operations and API calls in render function
• Utilities like sanitizing the HTML or outputting the base64 from generated svg
• Tests covering most of the functionality ensuring robustness

Installation

npm i d3-no-dom d3
#or
yarn add d3-no-dom d3
#or
pnpm add d3-no-dom d3

Thed3-no-domlibrary does not provide any underlying DOM implementation, giving users the flexibility to choose their preferred DOM library. Some options are:

• linkedom:A lightweight and fast DOM implementation ideal for serverless environments such asCloudflare WorkersorVercel Functions(recommended).

npm i linkedom
#or
yarn add linkedom
#or
pnpm add linkedom

• jsdom:A more comprehensive and heavier DOM implementation, suitable for traditional backend environments like monolithic applications hosted on dedicated servers.

npm i jsdom
#or
yarn add jsdom
#or
pnpm add jsdom

Warning

jsdommay not work on theCloudflare Workers without specifyingnodejs_compatflag due to use of the Node native modules

How to use

1. At first, you must supply your own d3 instance and dom provider to thed3-no-dom'sprepreSvgServerSideRenderer

• usinglinkedom(recommended)

  import*asd3from"d3"
  import{parseHTML}from"linkedom"
  
  //...
  
  classLinkedom{
  window:{document:Document};
  constructor(html:string){
  const{document,window}=parseHTML(html);
  this.window={document};
  Object.assign(this.window,window);
  }
  }
  
  const{render}=prepareSvgServerSideRenderer({
  domProvider:Linkedom,
  d3Instance:d3
  });

• usingjsdom

  import*asd3from"d3"
  import{JSDOM}from"jsdom"
  
  //...
  
  const{render}=prepareSvgServerSideRenderer({
  domProvider:JSDOM,
  d3Instance:d3
  });

2. Next, use therenderfunction. It provides everything you need in order to fully use d3.js on the server side (the underlying mechanism is integration with Virtual DOM)

// you can make e.g. API calls here
// it can also be synchronous if not needed!
// ╭────────────┤
// │ │
// ↓ ↓
constresult=awaitrender(async({d3Selection,svgNode,currentDom})=>{
// ↑ ↑ ↑ ↑
// │ d3 selected │ │ │
// │ object to work on ╯ │ ╰ whole DOM
// │ underlying
// ╰ rendered svg's svg DOM node to work on
// source, as HTML or base64
})

3. (Optionally) adjust your configuration or therender function's optionsdirectly in order to e.g. disable sanitizing the HTML or control the return value(whether it should be HTML or base64 - where second is specifically useful with usage withsatori)

License & contributing

The MIT License. All contributions are welcome!