Export & Import

Server-side Rendering with Node.js

Render Polotno JSON on your own servers with @polotno/image-export (PNG and JPEG, no headless browser) or polotno-node (headless Chromium, with raster PDF, GIF and MP4)

Two Node.js packages render Polotno JSON to images on your own servers. Both take the JSON the editor saves.

PackageHow it drawsOutputVideo and Lottie elements
@polotno/image-exportNo headless browser. Draws the canvas scene with Skia.PNG, JPEGNot drawn
polotno-nodeHeadless ChromiumPNG, JPEG, raster PDF, GIF, MP4Drawn

Use @polotno/image-export for still images: it is faster and uses less memory, see Speed and Memory. Use polotno-node for raster PDF, GIF and MP4 output, and for designs whose video frames or Lottie animations must appear in the output. Vector PDF needs neither package: @polotno/pdf-export runs in Node.js without a browser. The rest of this page covers polotno-node. To run no servers at all, use the Cloud Render API.

Render an image with polotno-node

Using polotno-node you can use most of the Polotno Store API. The common usage is image export from Polotno JSON:

const fs = require('fs');
// import polotno-node API
const { createInstance } = require('polotno-node');

async function run() {
  // create working instance
  const instance = await createInstance({
    // to create your own API key please go here: https://polotno.com/login
    key: 'nFA5H9elEytDyPyvKL7T',
  });

  // load sample json
  const json = JSON.parse(fs.readFileSync('polotno.json'));

  // then we can convert json into image
  const imageBase64 = await instance.jsonToImageBase64(json); // default is PNG
  // write image into local file
  fs.writeFileSync('out.png', imageBase64, 'base64');

  // also we can export design into lower size
  // and change image type
  const jpegImage = await instance.jsonToImageBase64(json, {
    pixelRatio: 0.5, // make image twice smaller
    mimeType: 'image/jpeg',
  });
  fs.writeFileSync('out.jpg', jpegImage, 'base64');

  // close instance
  instance.close();
}

run();

Render one file per record

To render one copy of a template per record, fill it with resolveVariables from @polotno/schema, then render the plain design it returns. polotno-node needs no option for it. @polotno/schema/variables is an ES module, so load it with import:

import { createInstance } from 'polotno-node';
import { resolveVariables } from '@polotno/schema/variables';

const instance = await createInstance({ key: 'YOUR_API_KEY' });

for (const row of rows) {
  const { design, issues } = resolveVariables(template, row);
  if (issues.length) console.warn(row, issues);
  const pdf = await instance.jsonToPDFBase64(design);
  // save or upload pdf
}

instance.close();

A design you render as it is draws its stored variable values, as the editor does.

Instance options

createInstance() accepts a few options that control the headless browser itself:

OptionDefaultPurpose
key:Your Polotno API key.
useFontCachetrueCache Google Fonts responses in memory and on disk, in polotno-node-font-cache under os.tmpdir(), shared by every process that uses that folder, and serve them to every page.
navigationTimeout120000Budget in milliseconds for the initial navigation to the client page.
protocolTimeout:Budget for individual DevTools protocol calls. Distinct from navigationTimeout.
requestInterceptor:Intercept page requests, for example to rewrite asset loads. Local files and cached fonts are answered before it, and requests the URL policy blocks never reach it.
executablePath:Launch this browser binary instead of the one polotno-node picks. Ignored when you pass your own browser.
headless'shell'Which headless mode to launch. Defaults to Chrome's headless shell wherever polotno-node resolves the browser itself. Pass true for full Chrome. Ignored when you pass your own browser.
browserArgs:Extra command-line flags, added to the flags polotno-node already passes.
const instance = await createInstance({
  key: 'nFA5H9elEytDyPyvKL7T',
  navigationTimeout: 240000, // 4 minutes, for a slow machine
});

navigationTimeout covers loading the client page, not rendering a design. Raise it if instance creation fails on a slow or heavily loaded machine. Setting it to 0 disables the limit, which turns a wedged load into a permanent hang rather than an error: prefer a large value over 0.

Use executablePath to run a browser the machine already has, such as /usr/bin/google-chrome-stable in a container image, instead of the one puppeteer downloaded.

Rendering designs from your users

When the design JSON comes from your users, render it with:

await instance.jsonToImageBase64(json, {
  blockPrivateNetwork: true, // no requests to localhost or private networks
  allowLocalFiles: false, // reject designs that name a file: source
});

The options work in every export method. By default, only cloud-metadata addresses such as 169.254.169.254 are blocked, and file: sources are served.

Every http(s) request a render makes for the design is checked: images, SVGs, fonts, media and each redirect hop. The Polotno license check and Google Fonts are not. A blocked request fails like any asset that does not load, and is logged with console.warn. With allowLocalFiles: false, a design that names a file: source is rejected with DESIGN_INVALID before rendering.

For your own allow rule, pass fetchGuard instead. It replaces the built-in checks:

await instance.jsonToImageBase64(json, {
  fetchGuard: (url) => new URL(url).hostname === 'cdn.example.com',
});

The same check is exported for your own fetches of design URLs:

import { guardedFetch } from 'polotno-node/ssrf-guard';

const res = await guardedFetch(url, { blockPrivateNetwork: true });

Also restrict outbound network access for the render process at the container or firewall level. The checks resolve hostnames before the request, and only a network rule also covers a DNS server that answers differently the second time.

Error Handling

Rendering failures inside the headless browser – broken images, missing fonts, invalid designs – are re-thrown on the Node side as plain Errors with a code (e.g. IMAGE_FAILED, FONT_FAILED, DESIGN_INVALID) and structured details such as elementId. Branch on the code, not the message text – see Error Handling. An asset that fails with a transient error – a reset connection, a DNS blip, a 5xx from the asset host – is retried automatically (three attempts in total, with backoff) before the render fails; there is nothing to turn on.

On this page