Performance & Optimization

These practices keep Takumi fast as your node trees grow.

The Renderer

Reuse the Renderer Instance

The Renderer holds Takumi's caches. Reuse one instance across renders instead of constructing a new one each time.

ImageResponse manages an internal renderer, or pass your own through the renderer option. See Typography & Fonts and Load Images.

Size the Resource Cache

Decoded images, SVG rasters, and parsed stylesheets share one byte budget, 16 MiB by default. The default suits a single-template server; raise it when many large images stay hot across renders:

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

Size the Glyph Cache

Resolved glyph outlines and their rasterized masks share a separate 8 MiB budget. These caches belong to the module rather than to a Renderer, so setGlyphCacheMaxBytes covers every renderer in the process and has to run before the first render — the budget is read when a cache is first used.

The default suits Latin text. A CJK outline runs a few kilobytes, so 8 MiB holds on the order of a thousand of them, and a page of Chinese re-rasterizes glyphs it just evicted:

import { setGlyphCacheMaxBytes } from "@takumi-rs/core";

setGlyphCacheMaxBytes(64 * 1024 * 1024);

takumi-js exports it as well. That one records the budget and applies it when the backend loads:

import { setGlyphCacheMaxBytes } from "takumi-js";

setGlyphCacheMaxBytes(64 * 1024 * 1024);

Preload Frequently Used Images

Loading images from URLs or bytes during the rendering pass is a bottleneck. Register Load Images to avoid re-decoding.

Parallel Rendering

On the server, prefer @takumi-rs/core: it renders across multiple threads, where @takumi-rs/wasm is single-threaded.

Component Design

Stack Filters in a Single Node

Each filtered node allocates its own offscreen composition layer, sized to the element (viewport-sized only as a worst case). Stacking filters on one node reuses a single layer.

Fonts

Prefer TTF over WOFF2