platform-documents

Template-based document generation engine supporting DOCX and PDF output. Uses pluggable renderers and template parsers with image processing via Sharp.

Package: @breadstone/archipel-platform-documents

npm install @breadstone/archipel-platform-documents

Quick Start

import { Module } from '@nestjs/common';
import { DocumentModule } from '@breadstone/archipel-platform-documents';
import { SharpImageProcessor } from '@breadstone/archipel-platform-documents/sharp';
import { DocxDocumentRenderer2 } from '@breadstone/archipel-platform-documents/docx';
import { PdfDocumentRenderer } from '@breadstone/archipel-platform-documents/pdf';

@Module({
  imports: [
    DocumentModule.forRoot({
      imageProcessor: SharpImageProcessor,
      renderers: [DocxDocumentRenderer2, PdfDocumentRenderer],
      maxImageWidth: 1920,
      maxImageHeight: 1080,
      delimiters: { start: '[[', end: ']]' },
      debug: false,
    }),
  ],
})
export class AppModule {}

---

Module Configuration

IDocumentModuleOptions

Property	Type	Default	Description
imageProcessor	Type<IImageProcessor>	—	Required. Image processor class (e.g. SharpImageProcessor)
renderers	Type<IDocumentRenderer>[]	—	Required. Renderer classes (e.g. [DocxDocumentRenderer2, PdfDocumentRenderer])
maxImageWidth	number	1920	Maximum width for embedded images
maxImageHeight	number	1080	Maximum height for embedded images
delimiters.start	string	'[['	Template variable start delimiter
delimiters.end	string	']]'	Template variable end delimiter
debug	boolean	false	Enable debug output

---

DocumentEngine

Main orchestrator for document rendering. Emits debug-level logs for document format detection and renderer initialization to aid troubleshooting.

Render from Template

import { DocumentEngine } from '@breadstone/archipel-platform-documents';

@Injectable()
export class InvoiceService {
  constructor(private readonly _docEngine: DocumentEngine) {}

  public async generateInvoice(data: IInvoiceData): Promise<Buffer> {
    const result = await this._docEngine.render({
      templateId: 'invoice-template',
      data: {
        invoiceNumber: data.number,
        customerName: data.customerName,
        items: data.items.map((item) => ({
          description: item.description,
          qty: item.quantity,
          unitPrice: `€${item.unitPrice.toFixed(2)}`,
          total: `€${(item.quantity * item.unitPrice).toFixed(2)}`,
        })),
        subtotal: `€${data.subtotal.toFixed(2)}`,
        tax: `€${data.tax.toFixed(2)}`,
        total: `€${data.total.toFixed(2)}`,
        date: new Date().toLocaleDateString('de-DE'),
      },
      templateFormat: 'docx',
    });

    return result.buffer;
  }
}

Render from Buffer

const templateBuffer = await fs.readFile('./templates/contract.docx');

const result = await this._docEngine.render({
  templateBuffer,
  data: { clientName: 'Acme Corp', startDate: '2025-01-01' },
  templateFormat: 'docx',
});

Templates with Images

const result = await this._docEngine.render({
  templateId: 'report-with-charts',
  data: {
    title: 'Q4 Report',
    summary: 'Revenue increased by 23%.',
  },
  images: [
    {
      tag: 'revenueChart', // Matches [[revenueChart]] in template
      buffer: chartImageBuffer,
      contentType: 'image/png',
      width: 800,
      height: 400,
    },
  ],
  templateFormat: 'docx',
});

---

Document Renderers

DOCX Renderer

Renders DOCX (Microsoft Word) documents using docxtemplater:

• Variable substitution: [[variableName]]
• Loops: [[#items]][[name]] - [[price]][[/items]]
• Conditionals: [[#if showDiscount]]...[[/if]]
• Image placeholders: [[imageName]]

PDF Renderer

Renders PDF documents using pdf-lib:

• Text substitution in PDF form fields
• Image insertion
• Page manipulation

---

Image Processing

SharpImageProcessor

Resizes and optimizes images before embedding in documents:

import { SharpImageProcessor } from '@breadstone/archipel-platform-documents';

// Used internally by DocumentEngine
// Respects maxImageWidth and maxImageHeight from module options

Supported formats: PNG, JPEG, WebP, TIFF, AVIF.

---

Real-World Example: Contract Generator

@Controller('api/v1/contracts')
export class ContractController {
  constructor(
    private readonly _docEngine: DocumentEngine,
    private readonly _blobService: BlobService,
  ) {}

  @Post(':id/generate')
  public async generate(@Param('id') contractId: string, @Res() res: Response): Promise<void> {
    const contract = await this._contractService.findById(contractId);

    const result = await this._docEngine.render({
      templateId: 'service-agreement',
      data: {
        clientName: contract.clientName,
        startDate: contract.startDate.toLocaleDateString('de-DE'),
        endDate: contract.endDate.toLocaleDateString('de-DE'),
        monthlyFee: `€${contract.monthlyFee.toFixed(2)}`,
        services: contract.services,
      },
      templateFormat: 'docx',
    });

    // Optionally store in blob storage
    await this._blobService.uploadFile(
      `contracts/${contractId}/${result.name}`,
      result.buffer,
      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    );

    res.set({
      'Content-Type': result.contentType,
      'Content-Disposition': `attachment; filename="${result.name}"`,
    });
    res.send(result.buffer);
  }
}

---

Error Handling

The library provides a hierarchy of domain error classes for structured error handling:

Error class	Base class	When thrown
DocumentError	Error	Base class for all document errors
DocumentRenderError	DocumentError	Template rendering failures (DOCX, PDF)
DocumentValidationError	DocumentError	Invalid templates, missing placeholders
ImageProcessingError	DocumentError	Image resize/conversion failures (Sharp)

import {
  DocumentRenderError,
  DocumentValidationError,
  ImageProcessingError,
} from '@breadstone/archipel-platform-documents';

All errors extend DocumentError, so a single catch (error instanceof DocumentError) handles any document-related failure.

---

Exports Summary

Export	Type	Description
DocumentModule	NestJS Module	forRoot() configuration
DocumentEngine	Service	Main rendering orchestrator
BaseDocumentRenderer	Abstract class	Renderer base
IDocumentRenderer	Interface	Renderer contract
SharpImageProcessor	Service	Image resize/optimization
IImageProcessor	Interface	Image processor contract
DocumentFormat	Enum	'docx' / 'pdf'
TemplateFormat	Enum	Template format identifiers
IRenderResult	Interface	Render output (buffer, name, contentType)
IDocumentProbeReport	Interface	Template validation report
DocumentError	Error class	Base document error
DocumentRenderError	Error class	Render failure error
DocumentValidationError	Error class	Validation failure error
ImageProcessingError	Error class	Image processing failure error