Caching
What Takumi keeps between renders, which renderer keeps it, and how to size, inspect, skip, or share it.
Takumi keeps decoded images, fonts, glyphs, and parsed styles between renders, so content that repeats costs less the second time. It keeps them in two layers. Each renderer keeps decoded work in its own memory, and a store keeps the bytes it downloads.
What a renderer keeps
A renderer keeps these kinds of work in one pool of memory, 128 MiB by default:
| Work | cache key |
|---|---|
| Decoded images and the rasters drawn from them | images |
| Glyph outlines and rasterized masks | glyphs |
Font files that renders and registerFont load | fonts |
| SVG images laid out to drawing ops | none |
| Parsed stylesheets | none |
| Compiled Tailwind classes | none |
Where glyphs cross a text-decoration line | none |
Faces that @font-face rules add | none |
Every render on that renderer reads from the pool and adds to it. When the pool is full, the renderer evicts the entries renders have not reused, whatever their kind, and a later render that needs one does the work again. A page heavy with images can use most of the pool, and a page of CJK text can fill it with glyphs, without either needing a setting.
The pool counts the estimated size of each entry, not the memory of the whole process. It does not count active renders, output buffers, or allocator overhead.
See Performance for measuring memory and render time.
The bytes a renderer downloads sit outside the pool, in its download store.
Which renderer owns a cache
render, renderSvg, renderAnimation, measure, and ImageResponse share one renderer, which takumi-js creates the first time you call any of them. Its pool lives for the life of the process.
A Renderer, PdfRenderer, or Painter you create keeps a pool of its own. Create it once, outside the request handler, so what it keeps survives between renders. Pass it to ImageResponse with the renderer option.
Set a renderer's cache size
Pass cache.maxBytes when you create the renderer:
import { } from "takumi-js/node";
const = new ({
: { : 256 * 1024 * 1024 },
});Raise maxBytes when renders keep redoing work that earlier renders did, such as decoding the same images. A larger pool helps only when later renders reuse what it keeps, so benchmark your own content first. A maxBytes of 0 keeps nothing in the pool between renders, except the fonts from registerFont, as Release fonts describes.
PdfRenderer and Painter take the same cache option.
The options apply when the renderer is created. To change them, create another renderer.
Keep none of one kind
Set images, glyphs, or fonts to "none" to keep none of that kind, while the other kinds still share the pool. Most renderers need none of these. Set one when you measured that one kind pushes out the others, such as a route that draws a different large photo on every request and evicts the glyphs every render reuses:
import { } from "takumi-js/node";
const = new ({
: {
: 256 * 1024 * 1024,
: "none",
},
});Each key defaults to "auto", which keeps that kind in the pool.
See what the cache holds
A renderer's cacheStats method reports what its caches hold and how often renders found what they looked up:
import { } from "takumi-js/node";
const = new ();
const { , } = .();
.(., .);
.(., ., .);memory covers the pool that every kind shares. current is the bytes it holds now. high is the most it held at once since the renderer was created.
images, glyphs, and fonts report each kind under its cache key. Each entry has these fields:
currentis the bytes the kind holds now.hitscounts lookups that found an entry, andmissescounts lookups that had to do the work again.evictionscounts entries released to stay withinmaxBytes.
The fonts entry counts the decoded font files the renderer holds, fonts from registerFont included. All sizes are the same estimates maxBytes counts, not the memory of the process, and the counts start when the renderer is created.
For the renderer that render and the other functions share, call cacheStats from takumi-js. It returns undefined until the first render creates that renderer:
import { } from "takumi-js";
const = ();
.(?..);A high miss count with many evictions means renders keep redoing work the cache dropped, so a larger maxBytes may help. A kind that holds most of memory.current while its hits stay low is a candidate for "none".
Skip caching an image
Every image source takes a cache mode, which decides whether the renderer keeps its decoded pixels:
auto, the default, keeps the decoded image in the renderer's pool.noneuses an image the cache already holds, but never adds one.
Use none for an image shown once, so it does not push out images worth keeping:
import { } from "takumi-js/response";
export function (: ) {
return new (< ="banner" />, {
: [
{
: "banner",
: () => (new ("/banner.png", .)).(() => .()),
: "none",
},
],
});
}To set the mode for every image in a render, pass images as an object instead of an array. The mode then covers the images Takumi fetches itself too, and a source's own cache still wins. A route that draws a different avatar on every request can keep the avatars out of the cache while its logo stays in:
import { } from "takumi-js/response";
export function (: ) {
const = new (.)..("avatar") ?? "";
return new (< ={} />, {
: {
: "none",
: () => new (). === "https://avatars.example.com",
: [
{
: "logo",
: () => (new ("/logo.png", .)).(() => .()),
: "auto",
},
],
},
});
}
function ({ }: { : string }) {
return (
<>
< ="logo" />
< ={} />
</>
);
}Takumi fetches the avatar URL itself, so it takes the render's none. The logo's own auto keeps it cached. The avatar URL comes from the request, so allowUrl keeps those fetches on one origin, as URLs from user input explains.
The decoded-image cache is keyed by a hash of the image's bytes, so the same image under two URLs decodes once. A data: URI in an <img> or a CSS url() always caches in auto mode, because the cache mode applies only to sources and to URLs Takumi fetches. A template that inlines its logo as a data: URI decodes it once.
Downloaded bytes
Renderers keep the bytes they download in a store, keyed by the URL they requested. That covers the images they fetch, the files @font-face rules load, and the fonts you list as URLs. A later render that needs one of them reads it from the store and skips the download, even after the pool evicted the decoded copy.
The store holds up to 32 MiB. When it is full, it drops the downloads that renders used least recently. A failed download never enters it. Every renderer in the process shares the store, and it lives as long as the process.
The store keeps downloads that resources with cache: "none" use too, since that mode only skips the decoded copy. The store's size does not count toward maxBytes, and its sizes are estimates that count the bytes and the URLs. The decoded copy of the same image or font counts in the pool as usual.
Renders that ask for the same URL at the same time each download it.
A stored download remembers the URL it came from after redirects. A render uses it only when its own allowUrl accepts that URL. Otherwise, the render downloads it again under its own policy and leaves the stored copy for other renders. Routes with different URL policies can share a renderer.
A render that passes its own fetch in images skips the store, since that fetch may send credentials or answer a relative URL differently for each user. Emoji images are the exception. They go to a store for each fetch function, since providers serve them at stable URLs.
fetchCache
images.fetchCache is deprecated. It still works, and a render that passes one keeps the images and @font-face files it downloads there instead of in the store. Fonts listed as URLs still go through the store.
Release fonts
A renderer keeps each font file a render loads in its pool, as one entry the size of the decoded file. A file counts once, however many renders, keys, or families load it. When the pool needs room, the renderer evicts the files renders have not reused, one file at a time, and a later render that lists one loads it again. This applies to fonts from a render's fonts list and to files that @font-face rules load.
Set fonts to "none" to let each file go as soon as no render uses it:
import { } from "takumi-js/node";
const = new ({ : { : "none" } }); A render holds every font file it uses until it finishes, whether it succeeds or fails, so another render cannot evict them. While renders hold more than maxBytes, the renderer keeps them all, and it evicts what no longer fits once they finish. With fonts: "none" or a maxBytes of 0, no font a render loaded stays after that render.
A font with cache: "none", and a googleFonts subset loaded for text, leaves once the render that loaded it settles.
Fonts from registerFont always stay. They count toward maxBytes, so they leave that much less room for the rest. A prepared render loads any @font-face file it draws with that the renderer evicted after prepare, and tries a rule's next src when that file fails to load again. To release fonts yourself, see Releasing fonts.
Google Fonts downloads
googleFonts keeps its CSS responses and the font files its subsets download in the download store of its fetch function. A request with signal or allowUrl uses the store too, under the same rules as a render's. maxBytes applies to stored responses as well. Its cache option takes your own Map of CSS responses in place of the store.
In Rust
The takumi crate keeps the same pool in a Cache. Build one with its own size, and pass it to each render that should share it:
use takumi::prelude::*;
let cache = CacheOptions::builder()
.max_bytes(256 << 20)
.images(ImageCacheMode::None)
.build();
let options = RenderOptions::builder()
.viewport(Viewport::new((1200, 630)))
.fonts(&fonts)
.node(node)
.cache(cache.clone())
.build();max_bytes sets the pool in bytes, and images, glyphs, and fonts take an ImageCacheMode, where ImageCacheMode::None keeps none of that kind. Cache::stats returns a CacheStats with the fields cacheStats reports. A render without cache uses Cache::shared(), one 128 MiB cache for the whole process. Cache::decode_image and Cache::parse_stylesheet decode images and parse CSS through a cache before a render, as the JavaScript renderers do.
Last updated on