Skip to main content

@quik/pdf

PDF template rendering and pdfmake integration for Quik.

Features​

  • YAML/JSON template DSL compiled to pdfmake document definitions.
  • Handlebars-style placeholders and helpers.
  • Dynamic control-flow nodes: repeat and when.
  • Table body supports row-level repeat blocks.
  • Template inheritance with merge strategies.
  • Optional preprocess hooks and clone strategy controls.
  • Optional PDF output helper: renderPdfBuffer(...).

Setup​

import { setup } from '@quik/pdf';

await setup({});

Register Templates​

import { PdfTemplatesStore } from '@quik/pdf';

await PdfTemplatesStore.load('reports', '/app/templates/pdf');

Templates are namespaced by module name. A file named summary.yml in reports becomes reports.summary.

You can also register templates programmatically.

Render Templates​

import { renderPdfTemplate } from '@quik/pdf';

const docDefinition = renderPdfTemplate('reports.summary', {
  title: 'Q1 Summary',
  rows: [ { label: 'Revenue', value: 1200 } ]
});

Render Options​

const docDefinition = renderPdfTemplate('reports.summary', data, {
  clone: 'safe',
  preprocess: [
    (definition) => ({
      ...definition,
      metadata: { generatedAt: new Date().toISOString() }
    })
  ],
  debug: false
});
  • preprocess: ordered transforms run before compilation.
  • clone: safe (default) or none.
  • debug: logs template resolution and preprocess order.

Dynamic Nodes​

repeat​

content:
  - type: repeat
    items: "{{rows}}"
    as: row
    indexAs: i
    content:
      - type: text
        value: "{{i}}. {{row.label}}"
    empty:
      - type: text
        value: "No rows"

Table rows can also be repeated directly inside table.body:

content:
  - type: table
    body:
      - [ "Label", "Value" ]
      - type: repeat
        items: "{{rows}}"
        as: row
        content:
          - [ "{{row.label}}", "{{row.value}}" ]
        empty:
          - [ "No rows", "" ]

when​

content:
  - type: when
    test: "{{showDetails}}"
    then:
      - type: text
        value: "Details enabled"
    else:
      - type: text
        value: "Details disabled"

Use strict condition helpers when needed:

content:
  - type: when
    test: '{{eq status "ok"}}'
    then:
      - type: text
        value: "{{translate \"report.ok\"}}"

Render Buffer​

import { renderPdfBuffer } from '@quik/pdf';

const buffer = await renderPdfBuffer('reports.summary', {
  title: 'Q1 Summary',
  rows: [ { label: 'Revenue', value: 1200 } ]
});

The helper uses current pdfmake setup and will initialize bundled VFS only when needed.

If you already have a compiled pdfmake definition:

import { renderPdfBufferFromDefinition } from '@quik/pdf';

const buffer = await renderPdfBufferFromDefinition({
  content: [ { text: 'Compiled document' } ]
});

Template Store Set/Upsert​

import { PdfTemplatesStore } from '@quik/pdf';

PdfTemplatesStore.set('reports.summary', { content: [] }, { replace: false });
PdfTemplatesStore.upsert('reports.summary', { content: [ { type: 'text', value: 'Updated' } ] });

Configuration​

  • pdf.templates.throwOnMissing: throw when a template key is missing (default: false).
  • pdf.templates.disableCache: reload templates from disk on every get() (default: false).
  • pdf.fonts: pdfmake font definitions (default: {}).

CLI Command​

When @quik/pdf is loaded together with @quik/cli, it registers:

  • pdf:validate - Validate a PDF template and optionally print compiled pdfmake JSON.

Documentation​

Full guide: docs/01_system/pdf.md.

API Reference​

Generated API documentation is available in the pdf API section.