Caching

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 you can give Takumi a store for the bytes it downloads. This page covers both layers, how to size or skip each one, and how to see what a renderer holds.

What a renderer keepsCopy Anchor Link

A renderer keeps these kinds of work in one pool of memory, 128 MiB by default:

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:

• Fonts that renders' fonts lists load, which have their own fonts budget.
• Fonts from registerFont.
• Active renders, output buffers, and allocator overhead.

See Performance for measuring memory and render time.

Three more caches sit outside the renderer:

• Downloaded image bytes, in a fetchCache you pass in.
• Emoji images, up to 8 MiB for each fetch function.
• Google Fonts CSS responses, up to 1 MiB and 64 responses for each fetch function.

Which renderer owns a cacheCopy Anchor Link

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

Pass cache.maxBytes when you create the renderer:

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

const renderer = new Renderer({
  cache: { maxBytes: 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. Fonts are counted apart, as Release fonts describes.

PdfRenderer and Painter take the same cache option.

Give one kind a budgetCopy Anchor Link

A budget caps how many bytes one kind of work may hold. Most renderers need none. 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 { Renderer } from "takumi-js/node";

const renderer = new Renderer({
  cache: {
    maxBytes: 256 * 1024 * 1024,
    budgets: { images: 64 * 1024 * 1024 }, 
  },
});

A kind with a budget evicts only its own entries to stay within the budget, so other kinds cannot push them out. The bytes it holds still count against maxBytes, so the pool shrinks as the kind fills its budget, and a budget the kind does not use stays available to the other kinds. A budget of 0 keeps none of that kind. The fonts budget works apart from the pool, as Release fonts describes.

Budgets never hold more than maxBytes together. Once the kinds with budgets fill it, a kind that needs more evicts its own entries instead of growing.

Change the cache of a running rendererCopy Anchor Link

A renderer's setCacheOptions method replaces its cache options while it keeps running:

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

const renderer = new Renderer();

renderer.setCacheOptions({ maxBytes: 32 * 1024 * 1024 }); 

It takes the same options as cache in the constructor, and replaces all of them. A key you leave out returns to its default, so the call above also removes any budget the renderer had. A smaller size or budget evicts what no longer fits right away. Changing only a size keeps what still fits. A kind that gains or loses a budget starts empty, and renders that are running when you call it finish with the entries they started with. PdfRenderer and Painter have the same method.

The shared rendererCopy Anchor Link

setCacheOptions from takumi-js sets the cache of the renderer that render and the other functions share:

import { setCacheOptions } from "takumi-js";

setCacheOptions({ maxBytes: 256 * 1024 * 1024 }); 

You can call it at any time. Once the shared renderer exists, the call applies to it right away, as the renderer's own setCacheOptions does. Before then, the renderer takes the options when it is created.

See what the cache holdsCopy Anchor Link

A renderer's cacheStats method reports what its caches hold and how often renders found what they looked up:

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

const renderer = new Renderer();

const { memory, budgets } = renderer.cacheStats(); 

console.log(memory.current, memory.high, memory.max);
console.log(budgets.images.hits, budgets.images.misses, budgets.images.evictions);

memory covers the pool that every kind except fonts shares. current is the bytes it holds now, budgets included. high is the most it held at once since the renderer was created, and max is its maxBytes.

budgets reports each kind under its budgets key, whether the kind has a budget or shares the pool. Each entry has these fields:

• current is the bytes the kind holds now.
• max is the kind's budget, or null when it has none.
• hits counts lookups that found an entry, and misses counts lookups that had to do the work again.
• evictions counts entries released to stay within maxBytes or the budget.

The fonts entry counts the fonts that renders' fonts lists loaded. It leaves out fonts from registerFont, since the budget never releases them. All sizes are the same estimates the budgets count, 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 { cacheStats } from "takumi-js";

const stats = cacheStats(); 

console.log(stats?.memory.current);

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 a budget.

Skip caching an imageCopy Anchor Link

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.
• none uses 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 { ImageResponse } from "takumi-js/response";

export function GET(request: Request) {
  return new ImageResponse(<img src="banner" />, {
    images: [
      {
        src: "banner",
        data: () => fetch(new URL("/banner.png", request.url)).then((res) => res.arrayBuffer()),
        cache: "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 { ImageResponse } from "takumi-js/response";

export function GET(request: Request) {
  const avatar = new URL(request.url).searchParams.get("avatar") ?? "";

  return new ImageResponse(<OgImage avatar={avatar} />, {
    images: {
      cache: "none", 
      sources: [
        {
          src: "logo",
          data: () => fetch(new URL("/logo.png", request.url)).then((res) => res.arrayBuffer()),
          cache: "auto", 
        },
      ],
    },
  });
}

function OgImage({ avatar }: { avatar: string }) {
  return (
    <div>
      <img src="logo" />
      <img src={avatar} />
    </div>
  );
}

Takumi fetches the avatar URL itself, so it takes the render's none. The logo's own auto keeps it cached.

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 image bytesCopy Anchor Link

The renderer keeps decoded pixels, not the bytes Takumi downloads. To reuse downloaded bytes and pending requests across renders, pass a fetchCache:

import { render } from "takumi-js";

const element = <img src="https://example.com/image.png" />;

const fetchCache = new Map<string, Promise<ArrayBuffer>>();

const image = await render(element, {
  images: {
    fetchCache, 
  },
});

fetchCache takes a Map<string, Promise<ArrayBuffer>> or any object with the same get, set, and delete methods. It is keyed by URL, and its values are promises, not raw buffers. The renderer's maxBytes does not cover it.

A fetchCache hit checks only the requested URL, because the cache does not record where a redirect led. If two routes check URLs differently, such as one with an allowUrl for user input and one that loads only your own files, give each route its own fetchCache. Otherwise one route can serve bytes the other fetched through a redirect its own check would have refused.

Emoji images from the emoji option are cached without a fetchCache, up to 8 MiB for each fetch function.

Release fontsCopy Anchor Link

A renderer keeps every font a render loads. The fonts budget caps the decoded bytes that renders' fonts lists may keep. These bytes count apart from maxBytes, so the pool and the fonts each keep their own bytes:

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

const renderer = new Renderer({ cache: { budgets: { fonts: 64 * 1024 * 1024 } } }); 

Past the cap, the least recently used families are released, and a later render that lists one loads it again. Fonts from registerFont always stay. The font loaded last also stays, even if it alone exceeds the cap, so with a cap of 0 the renderer keeps only its registered fonts and the last font a render loaded. Set the cap above what one render needs. To release fonts yourself, see Releasing fonts.

Google Fonts CSSCopy Anchor Link

googleFonts keeps the CSS responses it fetches, up to 1 MiB and 64 responses for each fetch function, and concurrent requests for the same URL share one fetch. Its cache option replaces that cache with your own Map. A request with signal or allowUrl skips the cache, so cancellation and URL checks stay with the caller. maxBytes applies to cache hits too.

In RustCopy Anchor Link

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 = Cache::builder()
  .max_bytes(256 << 20)
  .images(64 << 20)
  .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. Each budgets key has a setter of the same name in snake case, such as images, stylesheets, or font_faces, which gives that kind a budget in bytes. Cache::set_options takes a CacheOptions with the same fields and applies it to a cache in use, as setCacheOptions does. Cache::stats returns a CacheStats with the fields cacheStats reports, except fonts. The fonts budget belongs to the JavaScript renderers, so Cache has no setter for it. 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.