Performance
Reuse renderers, measure before you size the caches, and keep memory and render time down on a server.
Reuse the renderer, size its cache, and measure before you change the size. Each section below covers one of these steps and the limits that go with it.
Reuse the renderer
import { } from "takumi-js";
const = await (< ="p-8 text-4xl">Hello Takumi</>, {
: 1200,
: 630,
});render and ImageResponse share one renderer per process, so fonts, decoded images, and parsed stylesheets survive between renders without setup. Define the fonts list once at module level, so every render passes the same entries and each file decodes once. Caching lists what a renderer keeps and how to size its cache.
Share one renderer between requests
One Renderer takes overlapping calls without a lock. Concurrent requests can call render, prepare, renderSvg, renderAsDataUrl, measure, renderAnimation, and registerFont on it at once, and each call draws what it would draw alone with the same fonts. Two calls that list the same font load it once. On WebAssembly, JavaScript runs one call into the module at a time, and other calls run only while one waits for a font or image to download. The native renderer draws calls in parallel on worker threads, and each draw keeps the fonts it started with.
A few calls change what overlapping calls see:
unregisterFontandclearFontsremove fonts from calls that have not started drawing. A call that lists a removed font infontsloads it again. A call that relied onregisterFontdraws with the fallback font instead.- With
cache.fonts: "none", a call can release a font another call loaded. The other call loads it again before it draws. A call that lists several fonts can still draw without some of them. free()ends the renderer, and calls still in progress on WebAssembly reject withnull pointer passed to rust. Free a renderer only after its calls settle.
An aborted signal rejects its call with the signal's reason, an AbortError unless you pass abort() one of your own, or with the error of a loader that fails first. The call checks the signal between its steps and does not start the next one, so it ends early while it waits for downloads. When the signal aborts, a font or image loader that has already started, such as a data() function, finishes before the call rejects. When a loader fails first, the call rejects at once, and the other loaders that started keep running. Calls that share an images.fetchCache also share its downloads, so aborting one can reject another that waits for the same image. On the native renderer, a call still waiting for a worker thread rejects too. A draw that has already started runs to the end and resolves with its output instead of rejecting. The other calls on the renderer are unaffected.
A panic ends the process
The native addon is compiled with panic = "abort". A panic in Takumi, which is always a bug, ends the whole Node.js or Bun process with every request in it. Worker threads share the process, so rendering in a worker_threads worker does not contain it. To keep a crash from taking your server down, render in a child process. On WebAssembly, a panic throws RuntimeError: unreachable from that call instead, and the process keeps running. Please report the input that caused it.
Measure cold and repeated renders
Measure the first render separately from repeated renders, because font downloads and decoding slow the first one. Layout, painting, and encoding still run on a warm renderer. Use representative text, images, output formats, and concurrent requests. Compare latency and memory before you change the cache size. A larger cache helps only when later renders reuse what it keeps.
Keep memory flat on Linux servers
Each render allocates a few megabytes for its canvas and encoder buffers. On Linux, glibc keeps freed memory in its arenas, so a long-running process holds more memory than the renderer retains.
GLIBC_TUNABLES=glibc.malloc.mmap_threshold=262144 node server.jsglibc raises its mmap threshold after a large block is freed, so later canvases land in the arenas. A fixed threshold keeps buffers over 256 KiB in their own mappings, and glibc unmaps each one when it is freed.
| Setting | RSS over 1,275 renders | Render time |
|---|---|---|
| Default | 189–235 MB | Baseline |
GLIBC_TUNABLES=glibc.malloc.mmap_threshold=262144 | 114–130 MB | 5–7% slower |
MALLOC_ARENA_MAX=2 | 165–211 MB | 7% slower with 4 renders at once |
These figures come from one test setup, described in PR #1862. It used the node:24-bookworm-slim image on Linux arm64 and rendered 65 OG templates four at a time. Both settings apply to the whole process, so measure your own server first.
Alpine and other musl images
The glibc settings above do nothing on musl. Preload mimalloc to replace the allocator for the whole process:
apk add mimalloc2-insecure
LD_PRELOAD=/usr/lib/libmimalloc-insecure.so.2 node server.jsIn PR #2517, mimalloc raised four renders at a time from 259 to 546 a second, and peak RSS from 144 MiB to 178 MiB. The mimalloc2 package without -insecure is a hardened build and slower.
Keep network requests out of repeated work
Bundle fonts for a predictable startup without a font service. WOFF2 files are smaller but need decompression, while TTF files skip that step. A fonts list defined once decodes each file once, as long as the renderer keeps it (see Reusing fonts across renders). For repeated remote images, the download store keeps the bytes between renders.
Reduce painting work
Each filtered node needs an offscreen layer. Put filters on one node when they should apply to the same composed content. Moving filters from children to a parent can change the output, so compare the result.
Render large canvases
A canvas holds at most 64 megapixels, such as 8192 × 8192 or 4096 × 16384.
import { } from "takumi-js";
const = await (< ="p-8 text-4xl">Hello Takumi</>, {
: 3840,
: 2160,
});A larger viewport fails with Invalid viewport dimensions: a canvas holds 1 to 64 megapixels. Each pixel takes 4 bytes, so a full 64-megapixel render holds 256 MiB before encoding.
Painting cost follows the area a node covers, not the canvas size. A backdrop-filter blurs only the pixels under its node. A clip mask costs only the clipped box.
Last updated on