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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
@carbon/documents
PDF generation, email templates, ZPL labels, and QR/barcode utilities.
Always
- Style PDFs with
useTw()(react-pdf-tailwind), not rawStyleSheet— 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/nodefor QR/barcodes — there is noqrcodedependency; callgenerateQRCode()orgenerateBarcode()fromsrc/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.tsxpage shell or shared chrome components
Never
- Call
generateQRCodeSync— it throws "not supported" - Use
renderToBuffer— routes userenderToStream, drain to Buffer manually, wrap innew Uint8Array(body) - Copy
@react-pdf/rendererv4 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-docregistry.tsx - Fonts: bundled as base64 woff in gitignored
pdf/fonts.data.ts, generated byscripts/generate-fonts.mjs—latinandlatin-extsubsets 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 — everyNotificationEventthat sends mail (exceptDigest, which is in-app only), plus the transactional and lifecycle templates. Fixtures are not shipped (not exported fromindex.ts).pnpm email:previewsis the only way to view them — it serves the react-email dev server over that folder onEMAIL_DEV_PORT, and is whatcrbn up's Email app runs. Pointemail-dev.mjsat./src/emailby hand if you ever need the bare templates, but the four document emails error there (their props are DB view rows). The per-eventNotificationEmailfixtures are generated: edit thepreviewsarray inscripts/generate-notification-previews.mjs, re-run it, thenbiome check --writethe folder (the generator emits raw JSON indentation) - Exports:
./pdf,./email,./template,./zpl,./qr,./labels,./utils ./utilsis the CLIENT-SAFE entry point — pure display helpers with type-only deps:withRevisionSuffix(readableId, revisionId)is the one place thePO000123-1format is defined, andgetPurchaseOrderDisplayId/getQuoteDisplayIdare 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.tsis deliberately an explicit re-export list, notexport *: the per-document util files each define their owngetLineDescription
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 sideapps/erp/app/routes/file+/— PDF serving routes