HTML and CSS in, an image out. A small API that turns HTML into a PNG: social cards, link previews, quotes, anything you can lay out with flexbox. POST it the HTML and it sends back the image. No headless browser, no React, no JSX. Just HTML and CSS, laid out and drawn by a few thousand lines of plain JavaScript, with resvg turning the result into pixels.
It's named after the imago, the last stage of a moth's life, when it gets its wings. It's also Latin for "image". It's the sister project of mothwing, with the same idea: write the HTML yourself, and have as few dependencies as possible between it and the result.
imago used to be called html_png, which drove a headless Chrome through Selenium and needed Chrome, a matching chromedriver and Python. imago is a new engine written from scratch. It needs Node and nothing else, and renders a card in about 40 ms. The old { "html", "css" } request still works, see Coming from html_png.
imago isn't a browser. It understands the CSS a card needs: flexbox, blocks, absolute positioning, text, gradients, shadows, borders, images and transforms. It doesn't do grid, floats, tables, animations or JavaScript. If something's missing, it's left out quietly, not guessed at.
If you need the whole web platform, use Puppeteer or Playwright. If you're fine writing JSX, Satori is great. imago is for when you want to write plain HTML and keep the image server small.
imago is a server you run, not a package you install. Clone it, add your fonts, and start it:
git clone https://github.com/AlexFlipnote/imago.git
cd imago
npm install
mkdir fonts # put the .ttf, .otf or .woff files your cards use in here
cp config.example.json config.json # optional, see Configuration
npm start # http://localhost:3000Then POST some HTML:
curl -X POST "http://localhost:3000/?width=1200&height=630" \
-H "Authorization: <token>" \
--data-binary @examples/card.html -o card.pngTo update, git pull and npm install.
POST / with the HTML as the body, and the options as headers:
curl -X POST http://localhost:3000/ \
-H "X-Width: 640" -H "X-Height: auto" \
--data-binary @quote.html -o quote.png| Header | Default | |
|---|---|---|
X-Width |
auto |
The page's width in CSS pixels, or auto to be as wide as the page wants |
X-Height |
auto |
The page's height in CSS pixels, or auto to be as tall as the content |
X-Scale |
1 |
Pixel density, 2 turns a 1200x630 page into a 2400x1260 PNG |
X-Format |
png |
png or svg |
X-Background |
white |
Under the page when it sets no background itself, transparent for none |
The defaults can be changed in the config. The same options work in the query string (?width=640&height=auto), or in a JSON body with Content-Type: application/json: { "html": "...", "width": 640, "height": "auto" }. JSON can also have css, extra CSS that goes after the page's own. When more than one is given, JSON beats headers and headers beat the query string.
Auto sizes. Without a width or height, the image fits the page. auto width is as wide as the page gets without wrapping, so give the body a width or max-width, or one long line of text makes a very wide image. auto height lays the page out at that width and makes the image as tall as the content. For a fixed size, like a 1200x630 social card, send both. Absolutely positioned elements don't count towards either, same as in a browser, and vw and vh still measure against 1200x630.
The response has the final size in X-Width and X-Height. Any problems that didn't stop the render, like an image that failed to load, come back in X-Warnings. Errors come back as JSON: { "error": "..." }. GET / lists the loaded fonts and the default size.
Everything is in config.json, next to package.json. Without one, imago runs with the defaults, which means no token, so anyone who can reach it can POST. Copy config.example.json to get started:
{
"port": 3000,
"tokens": [
{ "name": "ffxiv.watch", "token": "a-long-random-string" },
{ "name": "alexflipnote.dev", "token": "another-long-random-string" }
],
"allowHosts": ["ffxiv.watch", "*.githubusercontent.com"]
}| Option | Default | |
|---|---|---|
port |
3000 |
|
host |
"0.0.0.0" |
"127.0.0.1" to only take requests from the same machine, like behind a reverse proxy |
fonts |
"fonts" |
The font folder, relative to the config |
tokens |
[] |
Who may POST, as { "name", "token" } or just the token. Each request sends one as Authorization: <token>, and the log shows the name. With none, anyone may POST. Tokens are at least 16 characters |
allowHosts |
[] |
Hosts remote images may come from. *.example.com allows its subdomains, * allows anything |
maxBodyBytes |
2097152 |
Largest request, 2 MB |
width |
"auto" |
Width when a request doesn't say, a number or "auto" |
height |
"auto" |
Height when a request doesn't say, a number or "auto" |
background |
"white" |
Background when a request doesn't say, "transparent" for none |
maxPixels |
4096 |
Largest side of an image, scale included. An auto side stops growing here |
cacheSize |
100 |
How many renders to remember, 0 for none |
workers |
"auto" |
Threads that render, one less than the CPU has by default. 0 renders on the main thread |
timeout |
10000 |
How long a render may take in ms before its worker is replaced and the request gets a 504 |
Changes apply while it runs. imago watches config.json, so you can add or remove a token, allow a new image host or add fonts and save, and the next request uses the new config. If the file doesn't parse, imago logs why and keeps the old config. Only port, host and workers need a restart.
Workers. Each render runs on a worker thread, so a big page doesn't hold up other requests and a stuck one can be stopped. When every worker is busy, requests wait in a queue, and a full queue answers 503. On a 16 core machine, 40 cards at once took 237 ms with workers and 471 ms without.
A token per site makes it easy to cut one off: delete its line, save, done.
A card is a normal HTML page. The body is the image, this one sized by its CSS:
<style>
body {
width: 1200px; height: 630px; box-sizing: border-box;
display: flex; flex-direction: column; justify-content: center;
padding: 80px; font-family: Inter; background: linear-gradient(135deg, #fffaf5, #f1ecff);
}
h1 { font-size: 72px; margin: 0; -webkit-line-clamp: 2 }
</style>
<h1>Write HTML, get an image back</h1>A few things differ from a browser, on purpose:
- With a height given,
htmlandbodyare as tall as the image, so centering works withoutheight: 100vh. The body has no margin either way. <img>and<svg>are laid out as blocks, so they can't sit inside a line of text.line-clampand-webkit-line-clampwork on any block, there's no need fordisplay: -webkit-box.
imago doesn't use system fonts, so a card always renders the same wherever it runs. It uses the fonts in its folder. font-family, font-weight and font-style pick between them like CSS does. sans-serif and other generic families get the first font, monospace the first monospaced one. A character the chosen font doesn't have comes from any other font that has it, so add a Noto font for each script you need.
Text is drawn as paths, with kerning but no ligatures or other shaping. Latin, Greek, Cyrillic and CJK look right. Arabic and the Indic scripts need shaping, which imago doesn't do yet. Variable fonts draw their default instance, so use one static font per weight. WOFF2 isn't supported yet either.
<img src> and background-image: url() take data URIs anywhere. Remote images only load from hosts in allowHosts, and files on the server never load. On the server, the HTML comes from whoever calls the API. Allowing * lets callers make it fetch any URL, including ones on your internal network, so only do that behind tokens.
Requests in the old shape still work. Send JSON with html and css, and the css is added after any <style> in the HTML:
{ "html": "<div class=\"container\"><h1>Hello</h1></div>", "css": ".container { display: flex; padding: .5em 1em }" }The old version also sized the image to the content, which is the default now too, and left it transparent. To get that as well, put this in config.json:
{ "background": "transparent" }Python, Chrome, chromedriver, pm2 and the Makefile are all gone. npm start runs it, under pm2 or systemd or whatever you like. The old README warned about images leaking the server's IP: remote images are now refused unless their host is in allowHosts, and <script> never runs, as there's no browser to run it.
- Selectors: tags, classes, ids, attributes,
>,+,~, descendants,:first-child,:last-child,:nth-child(),:not(),:is(),:where(),:root,:emptyand the-of-typeones. Specificity,!important,style="", custom properties andvar() - Layout:
displayblock, flex, inline-flex, inline-block, none and contents.flex-direction,flex-wrap,flexgrow, shrink and basis,order,gap,justify-content,align-items,align-self,align-contentand auto margins.width,height, min and max sizes,aspect-ratioandbox-sizing.positionrelative and absolute withinset.calc(),min(),max(),clamp(), and units frompxand%toem,rem,vwandvh - Text:
font-*,line-height,letter-spacing,word-spacing,text-align(justify too),text-transform,white-space,text-overflow: ellipsis,line-clamp,overflow-wrap,word-break,text-decorationandtext-shadow - Painting:
backgroundwith colors, linear and radial gradients (repeating too) and images withbackground-sizeandbackground-position,borderwith per-side colours and widths,border-radius(elliptical too), dashed and dotted borders,box-shadowinset and outset,opacity,overflow: hiddenwith rounded clipping,transformandtransform-origin,object-fit,object-positionandz-index - Images: PNG, JPEG, GIF, WebP and SVG, plus inline
<svg>that uses the text's colour forcurrentColor
The renderer is in src/index.js (renderPng and renderSvg), the API in src/server.js, the workers in src/pool.js and src/worker.js, and index.js starts it all.
npm test # node --test, with a fake font so it needs no files
npm run lint