Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

4.1 KB
Raw Blame

@carbon/documents

PDF generation, email templates, ZPL labels, and QR/barcode utilities.

Always

  • Style PDFs with useTw() (react-pdf-tailwind), not raw StyleSheet — semantic grays (gray-600 = heading, gray-800 = body) keep themes consistent across all blocks
  • Resolve async work before render — QR codes, barcodes, images, and fonts must be resolved to data URLs / registered before the synchronous component tree renders
  • Use @bwip-js/node for QR/barcodes — there is no qrcode dependency; call generateQRCode() or generateBarcode() from src/qr/
  • Route fonts through getSafeFontFamily() — every render path must use this: it returns the font stack (family, its Latin Ext face, Inter) so Central European letters render, and falls back to Helvetica so unregistered families never throw
  • Register new block-driven docs in pdf/preview-documents.tsx — DOCUMENT_PDFS[type] = { Component, sample } is required for the template preview route

Ask First

  • Adding a new document block type (coordinate with the template engine — see document-template-customizer.md)
  • Changing font bundling (woff format, NOT woff2 — react-pdf can't handle woff2/variable fonts)
  • Modifying the Template.tsx page shell or shared chrome components

Never

  • Call generateQRCodeSync — it throws "not supported"
  • Use renderToBuffer — routes use renderToStream, drain to Buffer manually, wrap in new Uint8Array(body)
  • Copy @react-pdf/renderer v4 examples — Carbon pins v3.x (different API)

Validation Commands

pnpm --filter @carbon/documents test        # vitest
pnpm --filter @carbon/documents typecheck   # tsc --noEmit
pnpm --filter @carbon/documents build       # generates fonts.data.ts

Key Patterns

  • Two PDF styles: block-registry driven (customizable) vs hand-built (fixed layout labels)
  • Block shape: ({ block, data }) => JSX.Element | null, keyed in per-doc registry.tsx
  • Fonts: bundled as base64 woff in gitignored pdf/fonts.data.ts, generated by scripts/generate-fonts.mjs — latin and latin-ext subsets as two families, the Latin Ext face's PostScript name suffixed -LatinExt (pdfkit dedupes embedded fonts by that name)
  • Email previews: src/email/previews/ holds one fixture per shipped email — every NotificationEvent that sends mail (except Digest, which is in-app only), plus the transactional and lifecycle templates. Fixtures are not shipped (not exported from index.ts). pnpm email:previews is the only way to view them — it serves the react-email dev server over that folder on EMAIL_DEV_PORT, and is what crbn up's Email app runs. Point email-dev.mjs at ./src/email by hand if you ever need the bare templates, but the four document emails error there (their props are DB view rows). The per-event NotificationEmail fixtures are generated: edit the previews array in scripts/generate-notification-previews.mjs, re-run it, then biome check --write the folder (the generator emits raw JSON indentation)
  • Exports: ./pdf, ./email, ./template, ./zpl, ./qr, ./labels, ./utils
  • ./utils is the CLIENT-SAFE entry point — pure display helpers with type-only deps: withRevisionSuffix(readableId, revisionId) is the one place the PO000123-1 format is defined, and getPurchaseOrderDisplayId / getQuoteDisplayId are the entity-shaped wrappers that delegate to it. Browser code (ERP UI, the /share/** pages) must import from here, NOT from ./pdf, which pulls the whole react-pdf graph into the bundle. src/utils/index.ts is deliberately an explicit re-export list, not export *: the per-document util files each define their own getLineDescription

Cross-References

  • .claude/rules/pdf-generation-patterns.md — full authoring guide
  • .claude/rules/email-design.md — the notification card every email template follows (anatomy, dark-mode-by-class, preview fixtures)
  • .claude/rules/document-template-customizer.md — block template engine
  • .claude/rules/printing-system.md — print queue / ZPL side
  • apps/erp/app/routes/file+/ — PDF serving routes