# How to Set Up html-to-pdfmake in Node.js: Complete Installation Guide

> Learn how to set up html-to-pdfmake in Node.js with our complete installation guide. Install the package and provide a JSDOM window instance for HTML to PDF conversion.

- Repository: [Aymeric/html-to-pdfmake](https://github.com/aymkdn/html-to-pdfmake)
- Tags: getting-started
- Published: 2026-02-26

---

**To set up html-to-pdfmake in Node.js, install the package via npm and provide a JSDOM window instance through the `window` option, as the core conversion engine in [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) relies on `window.DOMParser` to parse HTML strings into pdfmake document definitions.**

The html-to-pdfmake library transforms HTML strings or DOM trees into JSON structures compatible with pdfmake. According to the aymkdn/html-to-pdfmake source code, this conversion happens in [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) through a three-stage pipeline that creates a DOM, recursively walks the tree via `parseElement`, and aggregates styles through `applyStyle` before emitting the final document definition.

## Installation

Install html-to-pdfmake along with jsdom, which provides the required browser environment for Node.js:

```bash
npm install html-to-pdfmake jsdom

```

You will also need pdfmake itself to generate the actual PDF files:

```bash
npm install pdfmake

```

## Basic Node.js Setup

### The Window Requirement

The library is environment-agnostic but requires a `window` object containing `DOMParser`. In [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) at line 44, the constructor initializes the window context:

```javascript
this.wndw = (options && options.window ? options.window : window);

```

When running in Node.js, you must supply a fake window using JSDOM. Without this option, the library cannot parse the HTML string.

### Minimal Working Example

This example demonstrates the essential setup to convert HTML to a pdfmake definition and write a PDF file:

```javascript
// file: generate-pdf.js
const htmlToPdfMake = require('html-to-pdfmake');
const pdfMake = require('pdfmake/build/pdfmake');
const pdfFonts = require('pdfmake/build/vfs_fonts');
pdfMake.vfs = pdfFonts;

// Create a fake window for the library
const { JSDOM } = require('jsdom');
const { window } = new JSDOM('');

// Convert HTML to pdfmake definition
const html = `
  <h1>Hello World</h1>
  <p>This is <strong>bold</strong> and <em>italic</em> text.</p>
`;
const docDef = htmlToPdfMake(html, { window });

// Build and save PDF
const pdfDoc = { content: [docDef] };
pdfMake.createPdf(pdfDoc).getBuffer(buf => {
  const fs = require('fs');
  fs.writeFileSync('output.pdf', buf);
  console.log('PDF created successfully');
});

```

**Key point:** The `window` option passed to `htmlToPdfMake` is mandatory in Node.js environments.

## Configuration Options

As documented in the JSDoc header of [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) (lines 13-22), you can fine-tune the conversion by passing an options object as the second argument:

- **`window`** – The JSDOM window instance (required for Node.js).
- **`defaultStyles`** – Override or delete preset styles for HTML tags.
- **`tableAutoSize`** – Boolean to make table cells respect `width` and `height` CSS properties.
- **`imagesByReference`** – Boolean to return `{content, images}` structure for deduplicating large base-64 images.
- **`showHidden`** – Boolean to render elements with `display:none`.
- **`removeExtraBlanks`** – Remove unnecessary blank nodes from the output.
- **`removeTagClasses`** – Prevent the library from adding `html-${tag}` classes to elements.
- **`ignoreStyles`** – Array of CSS properties to ignore during parsing.

## Advanced Usage Examples

### Handling Images by Reference

When converting HTML containing inline images, use `imagesByReference` to separate image data from the document structure:

```javascript
const htmlToPdfMake = require('html-to-pdfmake');
const { JSDOM } = require('jsdom');
const { window } = new JSDOM('');

const html = `
  <h2>Report</h2>
  <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." />
  <p>End of report</p>
`;

const result = htmlToPdfMake(html, {
  window,
  imagesByReference: true
});

// result contains { content, images }
console.log(Object.keys(result.images)); // ['img_ref_...']

```

The `result.images` object maps reference IDs to base-64 strings, allowing you to manage image assets separately from the document definition.

### Rendering Hidden Elements and Complex Tables

To process hidden HTML elements and respect table cell dimensions:

```javascript
const html = `
  <div style="display:none">Hidden administrative note</div>
  <table>
    <tr>
      <th style="width:200px">Product</th>
      <th style="width:100px">Price</th>
    </tr>
    <tr>
      <td>Widget</td>
      <td>$10.00</td>
    </tr>
  </table>
`;

const docDef = htmlToPdfMake(html, {
  window,
  showHidden: true,
  tableAutoSize: true
});

```

The `showHidden` option forces the parser to include elements with `display:none`, while `tableAutoSize` applies CSS width/height values to the resulting pdfmake table layout.

## Summary

- **html-to-pdfmake** converts HTML strings into pdfmake-compatible document definitions through the logic defined in [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js).
- Node.js requires a JSDOM window instance passed via the `window` option because the library depends on `window.DOMParser` (line 44).
- The conversion pipeline creates a DOM, recursively processes nodes via `parseElement`, and applies styles through `applyStyle`.
- Configure output using options like `tableAutoSize`, `imagesByReference`, and `showHidden` to control table layouts, image handling, and visibility.
- See [`example.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/example.js) in the repository for a complete end-to-end implementation and [`test/unit.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/test/unit.js) for supported HTML constructs.

## Frequently Asked Questions

### Why does html-to-pdfmake require jsdom in Node.js?

The library relies on the browser's `DOMParser` API to convert HTML strings into traversable DOM trees. In [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js), the constructor explicitly looks for `this.wndw.DOMParser` to parse the input. Since Node.js lacks a native DOM implementation, you must provide a JSDOM window object that supplies this parser.

### What is the difference between using `imagesByReference: true` and the default image handling?

By default, html-to-pdfmake embeds base-64 image data directly into the content nodes. When you set `imagesByReference: true`, the function returns an object with `content` and `images` properties, where `images` is a separate map of reference IDs to base-64 strings. This allows pdfmake to deduplicate repeated images and reduces document definition size.

### How do I customize the default styles for HTML elements?

Pass a `defaultStyles` object in the options to override or remove preset styles. For example, to change how `<h1>` elements render, you would provide `{ defaultStyles: { h1: { fontSize: 24, bold: true } } }`. You can also delete defaults by setting a tag to `null`.

### Can I use html-to-pdfmake without installing jsdom as a dependency?

No, jsdom (or an equivalent library providing a `window` with `DOMParser`) is mandatory for Node.js usage. The source code in [`index.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/index.js) cannot parse HTML without this browser API. However, jsdom can be listed as a devDependency if you only use the library at build time, or you can use the pre-built [`browser.js`](https://github.com/aymkdn/html-to-pdfmake/blob/main/browser.js) bundle in environments where a real DOM is available.