av6-pdf-engine

av6-pdf-engine

av6-pdf-engine is a JSON-driven PDF layout engine built on top of PDFKit.
Describe your document once (page setup, styles, headers, blocks, tables, QR/barcodes, signatures, etc.) and render it to a file or in-memory buffer from any Node.js service.

Highlights

• JSON definition that mirrors pdfmake-style blocks while staying close to raw PDFKit features.
• Built-in layout helpers for headers, footers, watermarks, page backgrounds, and signature flows.
• Rich block catalog: text, columns, tables, key/value grids, images, QR codes, 1D barcodes, lines, and explicit page breaks.
• Automatic asset normalization for remote URLs, Buffers, or local paths (images, QR, barcode payloads).
• Custom font registration plus reusable style definitions with full TypeScript types.
• Two rendering targets: renderCustomPdf(def, "/tmp/doc.pdf") or renderCustomPdfToBuffer(def) for HTTP responses/storage.

Installation

npm install av6-pdf-engine
# or
pnpm add av6-pdf-engine
# or
yarn add av6-pdf-engine

Quick start

import { renderCustomPdfToBuffer, renderCustomPdf, CustomDocDefinition } from "av6-pdf-engine";

const doc: CustomDocDefinition = {
  pageSize: "A4",
  margins: { top: 80, right: 40, bottom: 80, left: 40 },
  fonts: [{ name: "Inter", src: "./assets/Inter-Regular.ttf" }],
  styles: {
    heading: { font: "Helvetica-Bold", fontSize: 16 },
    label: { color: "#999", fontSize: 9, bold: true },
  },
  header: {
    blocks: [{ type: "text", text: "ACME Corp — Invoice", style: "heading" }],
    backgroundColor: "#f7f7f7",
  },
  footer: (page, size) => ({
    blocks: [
      {
        type: "text",
        text: `Page ${page} / ${Math.round(size.height)}`,
        align: "center",
      },
    ],
  }),
  pageBackground: { src: "./assets/background.png", opacity: 0.05 },
  watermark: { text: "ACME CONFIDENTIAL", mode: "exceptFirst", opacity: 0.1 },
  content: [
    {
      type: "columns",
      widths: [200, "*"],
      columns: [
        [
          { type: "text", text: "Invoice #1234", style: "heading" },
          {
            type: "keyValueGrid",
            columns: [
              [
                { key: "Issued", value: "2025-12-01" },
                { key: "Due", value: "2025-12-15" },
              ],
            ],
            keyStyle: "label",
          },
        ],
        [
          {
            type: "table",
            widths: ["*", 80, 80],
            headerRows: 1,
            body: [
              [
                { text: "Item", style: "label" },
                { text: "Qty", style: "label", align: "right" },
                { text: "Total", style: "label", align: "right" },
              ],
              [{ text: "Consulting" }, { text: "12", align: "right" }, { text: "$3,000", align: "right" }],
            ],
          },
        ],
      ],
    },
    { type: "qr", value: "https://acme.example.com/pay/1234", size: 80 },
    { type: "barcode", value: "123456789012", bcType: "EAN13", width: 200 },
    { type: "signature", height: 100, label: "Authorized signature" },
  ],
};

// Write directly to disk
await renderCustomPdf(doc, "./tmp/invoice.pdf");

// Or capture an in-memory Buffer (perfect for HTTP responses / uploads)
const pdfBuffer = await renderCustomPdfToBuffer(doc);

Document definition

• pageSize: Any PDFKit-supported size ("A4", "LETTER", [width, height], etc.). Defaults to A4.
• margins: Required { top, right, bottom, left }. top/bottom double as header/footer bands.
• fonts: Optional array of { name, src } for custom TTF/OTF registration before rendering.
• header / footer: Structured block arrays. Footers can also be a single block, array, or a callback (pageNumber, pageSize) => Block | FooterDef.
• pageBackground: Optional image (path, URL, or Buffer) painted before content each page.
• watermark: Text watermark with opacity, angle, font size, color, and placement mode (all, first, last, exceptFirst, etc.).
• styles: Named StyleDef map that can be referenced via style on text/table cells/key-value items.
• content: Ordered array of Block objects (see below) rendered top to bottom with automatic pagination.

Block catalog

• text: Paragraph with typography controls (alignment, inline styles, links, margins).
• image: Local path, Buffer, or remote URL (auto-downloaded) with sizing/alignment.
• qr: QR codes via qrcode with size, version, and error correction level support.
• barcode: CODE128, EAN13, CODE39, ITF, CODE93 via bwip-js, including rotation, scaling, and caption text.
• columns: Multi-column layouts (widths, gaps, keepTogether) that can nest any other blocks.
• table: Simple table primitive with header rows, cell styles, and optional border layout hints.
• keyValueGrid: Responsive key/value pairs with shared or per-row styles, separators, and column widths.
• line: Horizontal rule with configurable width, color, and surrounding margins.
• pageBreak: Forces the renderer to finish the current page before continuing.
• signature: Reserves space (height/width) and optionally renders nested blocks or an image to support wet/digital signatures.

Each block supports a visible flag so you can skip rendering without mutating arrays.

Asset handling & async preparation

• Images, QR payloads, and barcodes accept paths, Buffers, or HTTPS URLs. Remote sources are fetched and cached as Buffers before rendering begins.
• Nested structures (columns, signature blocks, headers/footers) are traversed automatically, so you can reference assets anywhere in the tree.
• When using remote assets, ensure your runtime has outbound network access and consider wrapping renderCustomPdf* in your own caching layer.

Headers, footers, backgrounds, and watermarks

• Headers render inside the top margin band; footers render inside the bottom band. Adjust marginTop/marginBottom on header/footer defs for fine-grained spacing.
• pageBackground is painted before header/content on every new page, while watermark.mode decides which pages receive the overlay.
• Footer callbacks receive (pageNumber, pageSize) so you can display pagination, print timestamps, or conditionally hide content.

Contributors

• polarizz17

License

MIT — see LICENSE (provide your own if distributing).