HTML to Image in Node.js: 4 Ways, Same 6 Templates

There are four practical ways to turn HTML into an image in Node.js. We ran all four on the same six templates (a social card with Google Fonts, a receipt with a table, a transparent badge, a modern-CSS grid, a CJK/emoji/RTL card and a Chart.js chart) and timed them:

Short version: if your templates are real HTML and CSS, use a browser you launch once and reuse, or an API. Pick satori only when you design the template for satori from the start. The rest of this post shows the code for each, and the specific things that went wrong.

Tested on 2026-10-15 on macOS 27 (Apple M1 Pro), Node 22.18.0: [email protected] (Chrome 155.0.8059.79), [email protected], [email protected], @resvg/[email protected], @fontsource/[email protected]. Warm figures are the median of 5 runs, cold of 3. The API examples were run against a local mock of our API that checks the request body; we did not time the live API for this post.

The test templates

All six are full HTML documents at a fixed size, with user values passed through an escape function. They are the same templates we used for the Python version of this test, so the numbers can be compared across languages.

Method 1: Puppeteer and setContent

This is the baseline, and the method the other browser-based tools wrap. The complete script, with escaping and font handling explained step by step, is in render HTML to an image with Puppeteer. The core:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: 'shell' });
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1200, height: 630 });
  await page.setContent(html, { waitUntil: 'load' });
  await page.evaluate(() => document.fonts.ready); // web fonts are not covered by 'load'
  const png = await page.screenshot({ type: 'png' });
} finally {
  await browser.close();
}

The cold column used headless: true. The card and chart are slow even warm because they wait for the network: Google Fonts and the Chart.js CDN. Inlining the font cut the card to about 100 ms in a separate test. Everything rendered as designed; this is the reference for the pixel comparisons below.

Method 2: node-html-to-image

node-html-to-image wraps Puppeteer, adds Handlebars templating and manages a small puppeteer-cluster. Version 6.2.0 launches with headless: "shell", which starts faster than full Chrome. That is why its single calls beat our cold Puppeteer numbers.

npm install [email protected]

// nhti-card.mjs: node-html-to-image renders HTML with Puppeteer + Handlebars.
import nodeHtmlToImage from 'node-html-to-image';
import { readFile } from 'node:fs/promises';

const template = await readFile('card.hbs', 'utf8'); // {{title}} is escaped by Handlebars; {{{title}}} is not
await nodeHtmlToImage({
  output: 'nhti-card.png',
  html: template,
  content: { title: process.argv[2] ?? 'Ship faster with HTML templates' },
  type: 'png',
  waitUntil: 'load',
  // The default viewport is 800x600; set it to the card size or backgrounds repeat at 800px.
  puppeteerArgs: { defaultViewport: { width: 1200, height: 630 } },
});
console.log('wrote nhti-card.png');

Things to know:

• Batch, or pay the launch every time. Pass an array as content and it renders all items in one browser. Twenty cards took 4,570 ms, 229 ms each, with the default maxConcurrency: 2. Our own Puppeteer loop on one reused page did the same 20 cards in 1,662 ms.
• Escaping is Handlebars' job. {{title}} escapes; {{{title}}} inserts raw HTML. We passed Tom & Jerry <script> and the image showed the text, not a tag.
• It screenshots the body element by default (selector: 'body'), so a body smaller than the viewport gives a smaller image.
• It inherits Puppeteer's font timing. The load wait has the same font gap described in the Puppeteer post. Add a beforeScreenshot hook that waits for document.fonts.ready when you use remote fonts.

Method 3: satori (no browser)

satori, from Vercel, converts an element tree to SVG with its own layout engine. You convert the SVG to PNG with @resvg/resvg-js. No Chrome is involved, which makes it fast and small. The cost: it is not a browser, so it implements a subset of CSS.

npm install [email protected] @resvg/[email protected] @fontsource/[email protected]

// satori-card.mjs: element tree -> SVG (satori) -> PNG (resvg). No browser, no JSX build step.
import { readFile, writeFile } from 'node:fs/promises';
import satori from 'satori';
import { Resvg } from '@resvg/resvg-js';

// A tiny h() so we can skip JSX. Text children are plain strings: satori draws them as text,
// so user input needs no HTML escaping here (there is no HTML parser involved).
const h = (type, style, ...children) =>
  ({ type, props: { style, children: children.length === 1 ? children[0] : children } });

const title = process.argv[2] ?? 'Ship faster with HTML templates';

// satori needs font data as TTF, OTF or WOFF (not WOFF2).
const fonts = [
  { name: 'Inter', weight: 400, style: 'normal', data: await readFile('node_modules/@fontsource/inter/files/inter-latin-400-normal.woff') },
  { name: 'Inter', weight: 700, style: 'normal', data: await readFile('node_modules/@fontsource/inter/files/inter-latin-700-normal.woff') },
];

const card = h('div', {
    display: 'flex', flexDirection: 'column', justifyContent: 'space-between', width: '100%', height: '100%', boxSizing: 'border-box',
    padding: '72px 80px', background: 'linear-gradient(135deg, #0b1220, #13294b)', color: '#f8fafc', fontFamily: 'Inter',
  },
  h('div', { display: 'flex', alignSelf: 'flex-start', padding: '8px 18px', borderRadius: 999, background: '#22d3ee', color: '#0b1220', fontWeight: 700, fontSize: 24 }, 'Engineering'),
  h('div', { fontSize: 72, fontWeight: 700, lineHeight: 1.08 }, title),
  h('div', { display: 'flex', fontSize: 28, color: '#94a3b8' }, 'Simon Chiu, renderscreenshot.com'),
);

const svg = await satori(card, { width: 1200, height: 630, fonts });
const png = new Resvg(svg).render().asPng();
await writeFile('satori-card.png', png);
console.log(`satori-card.png: ${png.length} bytes`);

Four details in that file each cost us a failed render first:

1. boxSizing: 'border-box'. Without it the 72 px padding was added to the 630 px height and the author line fell off the bottom of the card, with no error.
2. A single child must not be wrapped in an array. With children: ['text'] on the last element, the line was silently missing.
3. Do not escape text for satori. We first used satori-html, which parses an HTML string. It escapes interpolated values itself, and satori draws entities literally: our title came out as Tom & Jerry <script>. The element-tree form above has no HTML parser, so plain strings are safe.
4. WOFF2 is not accepted. Pass .woff, .ttf or .otf data.

What happened when we ported our HTML templates

We fed the five static templates to satori through satori-html, first unchanged and then with a minimal port (rules for html, body and :root moved to a root div, and the font shorthand expanded, because satori 0.59.1 rejects it with Failed to parse declaration "font: ..."). Ported results:

None of this is a bug report against satori: its README documents a CSS subset, and the fix for each item is to design for that subset (flexbox, no tables, font files for every script you need, loadAdditionalAsset for emoji). The lesson for tool choice is that satori is a separate template language that looks like HTML, not an HTML renderer. Our node-html-to-image vs satori comparison looks at the card case in more detail.

Method 4: an HTML to image API

The fourth option keeps your HTML templates as they are and moves Chrome out of your process. With the RenderScreenshot Node SDK:

npm install renderscreenshot

// api-card.mjs: same HTML, rendered by the RenderScreenshot API.
import { writeFile } from 'node:fs/promises';
import { Client, TakeOptions, RenderScreenshotError } from 'renderscreenshot';
import { templates } from './templates.mjs'; // your template functions, values escaped

const client = new Client(process.env.RS_API_KEY);

try {
  const image = await client.take(
    TakeOptions.html(templates.card.html({ title: 'Ship faster with HTML templates' }))
      .width(1200)
      .height(630)
      .format('png')
      .waitFor('networkidle') // the card links Google Fonts
  );
  await writeFile('api-card.png', image);
} catch (err) {
  if (err instanceof RenderScreenshotError) {
    console.error(`${err.code} (retryable: ${err.retryable}): ${err.message}`);
  }
  process.exitCode = 1;
}

The SDK builder has no method for transparency, so the badge goes through the raw JSON body with "output": { "format": "png", "transparent": true }; the HTML to image API page shows that request. For many images, send them in one batch request instead of a loop.

When the API is the better trade:

• Your app runs on a platform where Chrome is painful (serverless size limits, Alpine images, no fonts installed).
• You need the CJK and emoji fonts that a minimal Linux container does not have.
• You render in bursts and do not want a browser process idling between them.

When it is not: you already run Chrome in the same process, your volume is tiny, or you need images without any network call.

Troubleshooting

Which one to choose

• A few templates you control, simple layouts, latency matters: satori, designed for satori from the first line.
• Real HTML/CSS, you already run Node on a server with Chrome: Puppeteer with one long-lived browser. Skip node-html-to-image unless you want Handlebars and its batching.
• Real HTML/CSS, and you would rather not operate Chrome: an API. The HTML to image API takes the templates above unchanged; get a free key and send the card template as your first request.

For the same comparison in another language, see HTML to image in Python. For what each approach does to PNG output specifically (transparency, size, CSS support across renderers), see render HTML to PNG.