html-to-pdf-headless

A Node.js package to generate PDFs and DOCX files from HTML strings without headless browsers like Puppeteer. Uses JSDOM, html-to-pdfmake, pdfmake, and docx under the hood.

Installation

npm install html-to-pdf-headless

Quick Start

const htmlToPdf = require("html-to-pdf-headless");
const fs = require("fs");

const html = `
  <h1>Invoice</h1>
  <p><strong>Name:</strong> John Doe</p>
  <table>
    <thead>
      <tr>
        <th>Item</th>
        <th>Qty</th>
        <th>Price</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Product A</td>
        <td>2</td>
        <td>$100</td>
      </tr>
      <tr>
        <td>Product B</td>
        <td>1</td>
        <td>$150</td>
      </tr>
    </tbody>
  </table>
`;

// Optional: custom styles for pdfmake classes
const styles = {
  "html-h1": {
    color: "#003366",
  },
};

htmlToPdf.createPdf(html, styles).getBuffer(function (buffer) {
  fs.writeFileSync("./output.pdf", buffer);
  console.log("PDF created successfully!");
});

API

createPdf(html, styles)

| Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | html | String | The HTML string to convert to PDF | | styles | Object | (Optional) pdfmake style definitions for CSS class names |

Returns a pdfmake document object. Use its methods to get the output:

• .getBuffer(callback) — get a Buffer (for saving to file or sending as a response)
• .getBase64(callback) — get a base64 string
• .getDataUrl(callback) — get a data URL

Example: Save PDF to File

htmlToPdf.createPdf(html, styles).getBuffer(function (buffer) {
  fs.writeFileSync("./report.pdf", buffer);
});

Example: Send PDF in Express Response

app.get("/pdf", (req, res) => {
  htmlToPdf.createPdf(html).getBuffer(function (buffer) {
    res.set("Content-Type", "application/pdf");
    res.set("Content-Disposition", 'attachment; filename="report.pdf"');
    res.send(Buffer.from(buffer));
  });
});

createDocFile(html)

| Parameter | Type | Description | | --------- | -------- | --------------------------------- | | html | String | The HTML string to convert to DOCX |

Returns a Promise<Buffer> that resolves with the .docx file contents.

Uses the same CSS inlining pipeline as createPdf, so <style> blocks, inline styles, and all supported CSS properties work identically.

Supported HTML Elements (DOCX)

| Element | Support | | ------------------------------------ | ------------------------------------ | | Headings (h1–h6) | Native Word heading styles | | Paragraphs (p, div) | Alignment, spacing, shading, borders | | Bold / Italic (b, i, em) | Fully supported | | Underline / Strikethrough (u, s) | Fully supported | | Links (a) | Hyperlinks with blue underline | | Lists (ul, ol, li) | Bulleted and numbered lists | | Tables (table, tr, td, th) | colspan, rowspan, cell shading | | Images (img) | Base64 data URIs only | | Preformatted text (pre) | Monospace font, preserved whitespace | | Blockquotes (blockquote) | Indented with left border | | Code (code) | Monospace with gray background | | Line breaks (br, hr) | Supported | | <style> blocks | Auto-inlined (same as PDF) |

Example: Save DOCX to File

const htmlToPdf = require("html-to-pdf-headless");
const fs = require("fs");

htmlToPdf.createDocFile(html).then(function (buffer) {
  fs.writeFileSync("./report.docx", buffer);
  console.log("DOCX created!");
});

Example: Send DOCX in Express Response

app.get("/docx", async (req, res) => {
  const buffer = await htmlToPdf.createDocFile(html);
  res.set("Content-Type", "application/vnd.openxmlformats-officedocument.wordprocessingml.document");
  res.set("Content-Disposition", 'attachment; filename="report.docx"');
  res.send(buffer);
});

Example: Generate Both PDF and DOCX from Same HTML

const htmlToPdf = require("html-to-pdf-headless");
const fs = require("fs");

const html = `<h1>Report</h1><p>Hello <strong>World</strong></p>`;

// PDF
htmlToPdf.createPdf(html).getBuffer(function (buffer) {
  fs.writeFileSync("./report.pdf", buffer);
});

// DOCX
htmlToPdf.createDocFile(html).then(function (buffer) {
  fs.writeFileSync("./report.docx", buffer);
});

Styling

CSS <style> Blocks (Recommended)

The package automatically inlines CSS from <style> blocks into each element. This means you can use CSS classes, IDs, element selectors, descendant selectors, and nth-child selectors:

<style>
  table { width: 100%; }
  th { background-color: #3498db; color: white; padding: 8px; }
  td { border: 1px solid #ddd; padding: 6px; }
  .highlight { background: #fff3cd; font-weight: bold; }
  tr:nth-child(even) { background: #f9f9f9; }
  h1 { color: #2c3e50; text-align: center; }
</style>

All matching CSS rules are applied as inline styles before PDF generation. Inline style="" attributes on elements always take priority over <style> block rules.

pdfmake Style Overrides

The converter also maps HTML tags to pdfmake style classes like html-h1, html-p, html-table, etc. You can override these via the styles parameter:

const styles = {
  "html-h1": { fontSize: 28, bold: true, color: "#003366" },
  "html-p": { fontSize: 12, margin: [0, 5, 0, 10] },
  "html-table": { margin: [0, 10, 0, 10] },
  "html-th": { bold: true, fillColor: "#EEEEEE" },
};

Supported HTML Elements

| Element | Support | | -------------------------------- | ----------------------------- | | Headings (h1–h6) | Font sizes + bold | | Paragraphs (p, div) | Margins, alignment | | Bold / Italic (b, i, em) | Fully supported | | Links (a) | Color + underline | | Lists (ul, ol, li) | Numbered and bulleted | | Tables (table, tr, td) | colspan, rowspan | | Images (img) | src attribute (base64 or URL) | | Line breaks (br, hr) | Supported | | Inline styles | Most CSS properties mapped | | <style> blocks | Auto-inlined to elements |

HTML Best Practices for PDF Generation

To get the best results, follow these guidelines:

1. Use valid HTML structure — Avoid putting <p> directly inside <tr>. Always wrap cell content in <td> or <th>.

   <!-- BAD -->
   <tr><p>Text</p></tr>
   
   <!-- GOOD -->
   <tr><td><p>Text</p></td></tr>

2. Don't nest <tr> inside <td> — This is invalid HTML and may produce unexpected results.

   <!-- BAD -->
   <td><tr><td>Nested</td></tr></td>
   
   <!-- GOOD: Use a nested table instead -->
   <td><table><tr><td>Nested</td></tr></table></td>

3. Use border on <td>/<th> for table borders — the border-collapse CSS property is not supported in pdfmake.

4. CSS <style> blocks work — CSS rules from <style> blocks are automatically inlined. Both inline styles and <style> blocks work.

5. Image sources — Use base64 data URIs for images. Remote URLs (http://...) are replaced with placeholder text since pdfmake in Node.js cannot fetch remote resources.

6. Table widths — Set width: 100% on your <table> element (via inline style or CSS class) to make tables span the full page width.

Known Limitations

• CSS @media queries are ignored (not relevant for PDF generation)
• Unsupported CSS properties like display, box-sizing, border-collapse, border-radius, box-shadow, position, float, overflow, and vendor-prefixed properties (-webkit-*, -ms-*) are automatically filtered out
• Fonts — Only Roboto is available by default. All CSS font families (sans-serif, Georgia, Arial, etc.) are mapped to Roboto
• Remote images — URLs (http://..., https://...) cannot be fetched; use base64 data URIs or local file paths instead
• CSS gradients — linear-gradient() and similar background values are not supported
• Padding — CSS padding is not supported by pdfmake and is ignored

License

ISC