Embedding files in PDFs - Chromiumly

Chromium converters and LibreOffice accept an embeds array to attach files to the generated PDF. Each item can be a file path string, a Buffer, or a ReadStream.

import { HtmlConverter } from "chromiumly";

const htmlConverter = new HtmlConverter();
const buffer = await htmlConverter.convert({
  html: "path/to/index.html",
  embeds: [
    "path/to/invoice.xml",
    "path/to/logo.png",
    Buffer.from("additional data"),
  ],
});

Embedded files are attached to the PDF and can be extracted in readers that support attachments. This is used for ZUGFeRD / Factur-X and similar standards that require embedding XML or other files inside the PDF — see Factur-X for the dedicated e-invoice option.

Attachment metadata

Optional embedsMetadata sets per-attachment metadata, keyed by filename, required for PDF/A-3 and Factur-X compliance:

type EmbedsMetadata = Record<
  string, // filename, matching an entry in `embeds`
  {
    mimeType?: string; // Written to the embedded file stream's /Subtype
    relationship?:
      | "Source"
      | "Data"
      | "Alternative"
      | "Supplement"
      | "Unspecified"; // The /AFRelationship value
  }
>;

const buffer = await htmlConverter.convert({
  html: "path/to/index.html",
  embeds: ["path/to/invoice.xml"],
  embedsMetadata: {
    "invoice.xml": { mimeType: "text/xml", relationship: "Data" },
  },
});

Embedding into existing PDFs

There’s also a dedicated PDFEngines.embed() route for attaching files to existing PDFs directly, without a conversion:

import { PDFEngines } from "chromiumly";

const embedded = await PDFEngines.embed({
  files: ["path/to/document.pdf"],
  embeds: ["path/to/invoice.xml", "path/to/logo.png"],
  embedsMetadata: {
    "invoice.xml": { mimeType: "text/xml", relationship: "Data" },
  },
});

See Embed files for the full dedicated-route reference.