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.
| Package | How it draws | Output | Video and Lottie elements |
|---|---|---|---|
@polotno/image-export | No headless browser. Draws the canvas scene with Skia. | PNG, JPEG | Not drawn |
polotno-node | Headless Chromium | PNG, JPEG, raster PDF, GIF, MP4 | Drawn |
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:
| Option | Default | Purpose |
|---|---|---|
key | : | Your Polotno API key. |
useFontCache | true | Cache 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. |
navigationTimeout | 120000 | Budget 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.
Related Pages
- Image Export - PNG and JPEG in Node.js without a headless browser
- Video Export - MP4 export in the browser and with polotno-node
- Cloud Render API - Managed rendering service without infrastructure
- Import and Export - Overview of all export formats
- Store API - Complete API reference
- JSON Schema - Structure reference for design JSON