node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

Templates

Register named templates and pass one to toPDF when you create an invoice.

The templates plugin registers named templates on a zugferd() instance. invoicer.template() returns the template you choose. Pass that return value to toPDF() on the invoice from create. toPDF() runs the template, then embeds the invoice XML in the PDF.

A template is a function you provide. It receives the invoice and returns a PDF. Drawing that PDF is the template's job. @node-zugferd/default-template, @node-zugferd/pdf-template, and @node-zugferd/docx-template are helpers you can register as templates.

Installation

Install the plugin

npm install @node-zugferd/templates@beta @node-zugferd/default-template@beta

Add the plugin to your instance

Register the plugin on the zugferd() instance that creates the invoice. templates is the map of templates, keyed by name. defaultTemplate is the name used when a call does not pass one.

invoicer.ts
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { templates } from "@node-zugferd/templates";
import { defaultTemplate } from "@node-zugferd/default-template";

export const invoicer = zugferd({
  profiles: [en16931],
  plugins: [
    templates({ 
      defaultTemplate: "default", 
      templates: { 
        default: defaultTemplate(), 
      }, 
    }), 
  ],
  // ...
});

Rendering

create returns the invoice. template() returns a function. toPDF() calls that function with the invoice, then stores the XML inside the PDF.

invoice.ts
const invoice = await invoicer.create("en-16931", data);
const pdf = await invoice.toPDF(invoicer.template());
const bytes = await pdf.save();

Pass props as the argument when the selected template accepts them:

invoice.ts
await invoice.toPDF(
  invoicer.template({
    locale: "de",
  }),
);

Pass a name to select a template other than the default. Props are the second argument:

invoice.ts
await invoice.toPDF(invoicer.template("compact", { accent: "blue" }));

Default template

@node-zugferd/default-template is a PDF invoice layout. Register it under a name, the same way as any other template.

npm install @node-zugferd/default-template@beta

It renders these profiles: Minimum, Basic WL, Basic, EN 16931, Extended, and XRechnung. Another profile throws ZugferdError. The message names the profile id and lists the supported ids: minimum, basic-wl, basic, en-16931, extended, xrechnung.

Built-in locales are en, de, and fr. The default locale is en. The default fonts are Helvetica, Helvetica Bold, and Helvetica Oblique. The default page size is A4. Pass translations to add a locale or replace a built-in one. A missing locale throws ZugferdError. The message names the locale and lists the locales from the merged translations.

invoicer.ts
import { defaultTemplate } from "@node-zugferd/default-template";
import { PageSizes } from "@node-zugferd/pdf-template";

defaultTemplate({
  defaultLocale: "de",
  defaultPageSize: PageSizes.A4,
});

Props passed to invoicer.template() override those defaults for one render:

Props

Prop

Type

Options

Prop

Type

PDF templates

@node-zugferd/pdf-template builds a template that draws on a PDF. definePdfTemplate creates the document, passes it to your function, and returns that document.

npm install @node-zugferd/pdf-template@beta
invoicer.ts
import { definePdfTemplate } from "@node-zugferd/pdf-template";

const compact = definePdfTemplate({
  async template(pdf, _props, ctx) {
    const page = pdf.addPage();
    page.drawText(ctx.profile.id, { x: 50, y: 800 });
  },
});

text draws a string. When its options include props, the string is formatted as an ICU message first. locale on those options is the message locale. The rest of the package is boxpdf, re-exported: layout nodes such as vstack, hstack, and table, plus fonts, page sizes, and themes.

definePdfTemplate checks for full ICU data in Node.js. Without it, the zugferd logger warns with Full ICU support is not available in this environment. Please ensure that your Node.js environment has full ICU support enabled. The template still runs.

DOCX templates

@node-zugferd/docx-template fills a Word file and converts the result to PDF. defineDocxTemplate takes the template file as a Blob, ArrayBuffer, or Uint8Array, or as a function of the props and context. The filled document is converted to PDF with LibreOffice through @matbee/libreoffice-converter. toPDF() receives those PDF bytes. The converter is created the first time a DOCX template renders.

npm install @node-zugferd/docx-template@beta
invoicer.ts
import { readFile } from "node:fs/promises";
import { defineDocxTemplate } from "@node-zugferd/docx-template";

const letter = defineDocxTemplate({
  templateFile: await readFile("./letter.docx"),
});

The Word file is processed with easy-template-x. Empty tags are skipped. The scope is the invoice under data and the template props under props. Nested objects are collapsed into dotted keys, so a seller name is the key data.seller.name. Arrays stay arrays, and each object in an array is flattened the same way. An array item that has a _type field is passed through unchanged, which is how easy-template-x represents images and other rich content.

Custom templates

Each entry in templates has a template function. props is the object passed to invoicer.template(). ctx is the invoice. The function returns a PDF document, PDF bytes, or a string of PDF data. With no props, it receives {}.

invoicer.ts
templates({
  templates: {
    note: {
      async template(_props, ctx) {
        ctx.data;
        ctx.xml;
        ctx.profile;
        ctx.context;
      },
    },
  },
});

ctx.data is the invoice data. ctx.xml is the XML from create. ctx.profile is the profile used for that invoice. ctx.context is the zugferd context.

props is an optional Standard Schema. When it is set, the props are validated before template runs. A failed schema throws ZugferdValidationError.

transformProps runs after that validation, when a props value is present, and before template. It receives the props and ctx, and its return value is what template receives.

invoicer.ts
templates({
  templates: {
    note: {
      props: propsSchema,
      async transformProps(props, ctx) {
        return { ...props, title: ctx.profile.id };
      },
      async template(props, ctx) {
        // ...
      },
    },
  },
});

Errors

A call with no name, and no defaultTemplate, throws ZugferdError with the message No template name provided and no default template configured.

A name that is not a key of templates throws ZugferdError with the message Template "<name>" not found in templates configuration.

A props schema that rejects the props throws ZugferdValidationError. The template function does not run.

Options

Prop

Type


 

llms.txt
Parser

Read Factur-X and ZUGFeRD invoices from XML or PDF/A-3.

TRAFFIQX®

Send and receive electronic invoices through the TRAFFIQX® Invoice API (TIA).

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceRenderingDefault templatePropsOptionsPDF templatesDOCX templatesCustom templatesErrorsOptions

How is this guide?