Polotno to Vector PDF

Convert Polotno JSON into a vector PDF, in Node.js or directly in the browser. Optional PDF/X-1a print-ready export (Node only).

npm install @polotno/pdf-export

Node usage

import fs from 'node:fs';
import { jsonToPDF } from '@polotno/pdf-export';

const json = JSON.parse(fs.readFileSync('./polotno.json', 'utf8'));
await jsonToPDF(json, './output.pdf');

jsonToPDFBytes(json, attrs) is also exported on the Node entry — useful when you want raw bytes (to upload, attach, etc.) without writing to disk.

Browser usage

import { jsonToPDFBlob } from '@polotno/pdf-export/browser';

async function exportToPDF(store) {
  const blob = await jsonToPDFBlob(store.toJSON());
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'design.pdf';
  document.body.appendChild(a);
  a.click();
  a.remove();
  URL.revokeObjectURL(url);
}

Also exported: jsonToPDFBytes(json, attrs): Promise<Uint8Array> — for cases where you want raw bytes (to push to IndexedDB, send via WebTransport, share via navigator.share, etc.).

The browser entry does not support attrs.pdfx1a / attrs.validate — those rely on Ghostscript, which has no browser-side equivalent. Pass them and you'll get a clear runtime error pointing at the Node entry.

CORS

When polotno designs reference remote images, fonts, or SVG sources, the browser fetches those assets at export time. They must be reachable with CORS:

• Google Fonts (fonts.googleapis.com and fonts.gstatic.com) work out of the box.
• Custom asset URLs must be served with Access-Control-Allow-Origin: * (or your origin), or pre-fetched and passed as data: URLs in the JSON.

PDF/X-1a print-ready export (Node only)

For professional printing:

await jsonToPDF(json, './print-ready.pdf', { pdfx1a: true });

// With custom metadata and validation
await jsonToPDF(json, './book-cover.pdf', {
  pdfx1a: true,
  validate: true,
  metadata: {
    title: 'My Book Cover',
    author: 'Author Name',
    application: 'KDP CoverCreator v1.0',
  },
});

Requires Ghostscript:

• macOS: brew install ghostscript
• Ubuntu: apt-get install ghostscript
• Windows: download from ghostscript.com

Spot color / foil support

For professional printing with special inks like metallic foils or Pantone colors:

await jsonToPDF(json, './output.pdf', {
  pdfx1a: true,
  spotColors: {
    'rgba(255,215,0,1)': {
      name: 'Gold Foil',
      pantoneCode: 'Pantone 871 C', // optional reference
      cmyk: [0, 0.15, 0.5, 0],      // CMYK fallback (0–1 range)
      overprint: true,              // recommended for foils — see below
    },
    '#C0C0C0': {
      name: 'Silver Foil',
      cmyk: [0, 0, 0, 0.25],
      overprint: true,
    },
  },
});

Any element with a matching fill or stroke color is automatically converted. Color matching is flexible — '#FFD700', '#ffd700', 'rgb(255,215,0)', and 'rgba(255,215,0,1)' all match. CMYK fallback values are used by viewers that don't support spot colors.

Supported on text, lines, figures, and SVG elements.

Overprint

overprint: true emits the PDF graphics state /OP true /op true /OPM 1 whenever the spot color is painted, telling the press to add the spot ink on top of any underlying CMYK rather than knocking it out:

• Without overprint (default): the spot region knocks out CMYK underneath. A misaligned foil die produces a visible white halo at the edge.
• With overprint: CMYK prints continuously through the spot region; the foil is stamped over it. No halo, underlying artwork stays intact.

Acrobat's Output Preview → Simulate Overprinting shows how the press will composite the layers. Verify spot colors in Tools → Print Production → Output Preview → Separations.

For foil regions, prefer plain shapes or simple SVG paths — SVGs that internally use <clipPath> or <mask> may have their spot color flattened to CMYK during PDF/X-1a conversion.

Bleed and crop marks

For print production you usually want extra paper around the trim edge so that ink covers the cut line, plus crop marks for the print shop:

await jsonToPDF(json, './print-ready.pdf', {
  pdfx1a: true,
  includeBleed: true,   // expand each page by `page.bleed` px on every side
  cropMarkSize: 18,     // reserve 18 px around the bleed for crop marks
});

Set bleed in pixels on each page in the JSON:

{ width: 1080, height: 1080, pages: [{ background: '...', bleed: 36, children: [...] }] }

Element coordinates stay relative to the trim corner — (0, 0) still lands at the top-left of the trim. Backgrounds automatically extend into the bleed strip.

The output PDF gets correct PDF/X page boxes (MediaBox ⊇ BleedBox ⊇ TrimBox = ArtBox) so RIPs and proofers can identify the live area without guessing.

Works on both Node and browser entries — no Ghostscript required if you skip pdfx1a.

DPI handling

The library converts pixel coordinates to PDF points using the dpi value from your JSON (default 72):

const json = { width: 1920, height: 1080, dpi: 300, /* ... */ };

// Uses JSON dpi automatically
await jsonToPDF(json, './output.pdf');

// Or override
await jsonToPDF(json, './output.pdf', { dpi: 150 });

A 1920×1080 canvas at 300 DPI is 6.4″ × 3.6″ in the PDF; at 72 DPI it's 26.67″ × 15″.

Development

npm install            # postinstall applies patches/ to node_modules
npm run build          # builds the Node and browser bundles
npm test               # Node-side fixture tests
npm run test:browser   # real-Chromium smoke suite (Vitest browser mode)
npm run dev            # demo Polotno editor for manual export testing