Performance & Optimization

Reuse the rendererCopy Anchor Link

import { render } from "takumi-js";

const image = await render(<div tw="p-8 text-4xl">Hello Takumi</div>, {
  width: 1200,
  height: 630,
});

render and ImageResponse reuse one managed renderer, so they need no cache setup. If you create a Renderer yourself, create it outside the request handler. Its registered fonts and decoded resources then survive between renders.

Know what is cachedCopy Anchor Link

Cache budgets count retained entries, not total process memory. Fonts, active renders, output buffers, and allocator overhead use memory too. See image caching and Google Fonts for resource-specific behavior.

Measure cold and repeated rendersCopy Anchor Link

Measure the first render separately from repeated renders. 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 a budget. A larger cache helps only when later renders reuse what it keeps.

Resource cacheCopy Anchor Link

import { Renderer } from "takumi-js/node";

const renderer = new Renderer({ cacheMaxBytes: 64 * 1024 * 1024 }); 

Raise the budget when reused images or stylesheets get evicted. For an image used once, cache: "none" keeps it from pushing out reusable entries. This budget does not cover images.fetchCache, so bound that cache yourself.

Glyph cacheCopy Anchor Link

import { setGlyphCacheMaxBytes } from "takumi-js";

setGlyphCacheMaxBytes(64 * 1024 * 1024); 

Call it before the first render. A later call does not resize a cache already in use. Every renderer in the same backend module shares this budget. Large glyph sets, such as CJK text, can need more space. Benchmark your content first.

Keep memory flat on Linux serversCopy Anchor Link

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.js

glibc 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.

These figures come from one test setup, described in PR #1862: the node:24-bookworm-slim image on Linux arm64, rendering 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 use a different allocator.

Keep network requests out of repeated workCopy Anchor Link

Bundle fonts for a predictable startup without a font service. WOFF2 files are smaller but need decompression. TTF files skip that step. A reused renderer decodes a registered file once. See Fonts in CI and offline renders.

For repeated remote images, use a bounded fetch cache. The renderer's decode cache does not replace a download cache.

Reduce painting workCopy Anchor Link

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 canvasesCopy Anchor Link

A canvas holds at most 64 megapixels: 8192 × 8192, or 4096 × 16384.

import { render } from "takumi-js";

const image = await render(<div tw="p-8 text-4xl">Hello Takumi</div>, {
  width: 3840,
  height: 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.