Images & emoji

External imagesCopy Anchor Link

render() and ImageResponse fetch every remote http:// or https:// URL the tree references:

• an <img> src
• background-image, mask-image, and list-style-image in a node's style or tw

Takumi does not fetch URLs inside css or a <style> tag. Pass those images as pre-fetched images.

Share a fetchCache across renders to reuse downloaded bytes and pending requests:

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. Values are promises, not raw buffers.

A plain Map never evicts entries. If each render uses a different URL, pass a bounded cache such as an LRU, or leave fetchCache out.

Fetch limitsCopy Anchor Link

import { render } from "takumi-js";

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

const image = await render(element, {
  images: {
    timeout: 3000,
    maxBytes: 4 * 1024 * 1024,
    allowUrl: (url) => new URL(url).hostname === "example.com",
  },
});

images, googleFonts, and fontFromUrl take these options. A custom data loader makes its own requests, so they do not apply to it.

RetriesCopy Anchor Link

GET and HEAD requests make up to three attempts. They retry when fetch throws a TypeError (such as a connection error) or a TimeoutError, and on HTTP 408, 429, 500, 502, 503, and 504. The waits are 100 ms, then 200 ms. A Retry-After header can extend a wait up to one second. A longer Retry-After returns the error without retrying.

These stop retries:

• the caller's signal aborts
• the deadline passes
• any other HTTP error
• a failure while reading the response body

A custom fetch must honor the abort signal it receives.

URLs from user inputCopy Anchor Link

Takumi fetches these URLs from your server. Set allowUrl whenever user input can reach the markup.

• allowUrl checks each redirect destination, up to five hops. Each hop shares the same deadline and gets its own attempts.
• A fetchCache hit checks only the requested URL, because cached bytes keep no redirect history. Do not share one fetchCache across different URL policies.
• allowUrl sees URLs, not IP addresses. To filter by resolved address, pass a custom fetch.

Pre-fetched imagesCopy Anchor Link

Give images a key so the renderer never fetches them. Use the key in any src or CSS url().

import { ImageResponse } from "takumi-js/response";

export function GET(request: Request) {
  return new ImageResponse(<OgImage />, {
    images: [
      {
        src: "my-logo",
        data: () => fetch(new URL("/logo.png", request.url)).then((res) => res.arrayBuffer()),
      },
      {
        src: "background",
        data: () => fetch(new URL("/background.png", request.url)).then((res) => res.arrayBuffer()),
      },
    ],
  });
}

function OgImage() {
  return (
    <div
      style={{
        backgroundImage: "url(background)",
      }}
    >
      <img src="my-logo" />
    </div>
  );
}

data is raw bytes or a function that returns them. Takumi skips fetching any remote URL that already has an entry.

Raw pixelsCopy Anchor Link

Pass raw RGBA pixels instead of encoding a PNG first; Takumi skips decoding. The Bitmap helper renders a row-major buffer of width * height * 4 bytes as an <img>. This example fills a 64 × 64 image with opaque blue:

import { render } from "takumi-js";
import { Bitmap } from "takumi-js/helpers/jsx";

const pixels = new Uint8Array(64 * 64 * 4);

for (let offset = 0; offset < pixels.length; offset += 4) {
  pixels.set([59, 130, 246, 255], offset);
}

const image = await render(<Bitmap width={64} height={64} data={pixels} />, {
  width: 64,
  height: 64,
});

Set premultiplied when the bytes already have premultiplied alpha. Takumi then uses them as they are. Outside JSX, an image node's src takes the same { width, height, data, premultiplied? } object.

Decode cachingCopy Anchor Link

Takumi caches each decoded image, so repeated content decodes once. There are two caches:

A data: URI in an <img> or a CSS url() uses the same decode cache, keyed by the bytes it holds. A template that inlines its logo decodes it once. data: URIs always cache in auto mode, because images.cache applies only to sources and to URLs Takumi fetches.

The decode cache belongs to the renderer and has a byte budget, 64 MiB by default. Each entry counts its decoded size. When the cache is full, it evicts the least recently used entry. SVG sources, their rasterized pixels, and parsed stylesheets share the same budget. A workload with a different image every render does not grow memory. It misses the cache and decodes each time.

Set the budget when you create the renderer. 0 turns caching off.

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

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

The per-image cache mode takes two values:

• auto (default): cache the decoded image within the budget.
• none: read the cache but never add to it. Use it for a one-off image, 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. This includes images Takumi fetches itself. A source's own cache still wins. For a route that renders a different image on every request, cache: "none" keeps one-off decodes out of the cache:

import { ImageResponse } from "takumi-js/response";

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

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

Decode limitsCopy Anchor Link

Takumi rejects oversized images when it decodes them. The limits protect servers from decode bombs: small files that declare huge dimensions to force huge allocations.

EmojiCopy Anchor Link

takumi-js turns emoji into images by default. It splits each emoji out of the text and fetches its SVG from a CDN, using Twemoji unless you pick another set.

Dynamic fetchingCopy Anchor Link

Set emoji to choose the set. The options match satori: twemoji (default), blobmoji, noto, openmoji, fluent, and fluentFlat. render, renderSvg, renderAnimation, measure, and ImageResponse all take it.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div tw="flex justify-center items-center text-3xl">Hello 👋😁</div>, {
    emoji: "noto", 
  });
}

Emoji detection follows the Unicode presentation rules. A pictograph that defaults to text presentation, such as ‼ or ▶, stays text and renders with your fonts. Add U+FE0F after it to force the emoji image. Add U+FE0E after an emoji to keep the text glyph.

Manual extractionCopy Anchor Link

The extractEmojis helper does the splitting. It replaces each emoji with an image node that points at the CDN. Call it yourself to fetch emoji with your other images on your own renderer.

import { extractEmojis } from "takumi-js/helpers/emoji";
import { fromJsx } from "takumi-js/helpers/jsx";
import { prepareImages } from "takumi-js/helpers";
import { Renderer } from "takumi-js/node";

let { node } = await fromJsx(<div tw="flex justify-center items-center text-3xl">Hello 👋😁</div>);
node = extractEmojis(node, "twemoji");

const images = await prepareImages({ node });

const renderer = new Renderer();

const image = await renderer.render(node, {
  images,
});

prepareImages fetches the remote URLs missing from sources. It returns the supplied sources and the fetched entries together. It takes the same fetch cache and limits.

COLR / bitmap fontsCopy Anchor Link

Takumi draws emoji from color fonts: COLR fonts such as Twemoji-COLR, and bitmap fonts such as Noto Color Emoji. A COLR file is much smaller than a bitmap font. The glyphs come from the loaded font, so no emoji request goes out.

• Register the font through fonts.
• Set emoji: "from-font".

Variation selectors take priority over font order. A code point followed by U+FE0F renders as a color emoji, even when a text font comes first in the stack. A code point followed by U+FE0E renders as a monochrome glyph, even when a color font comes first. Bare code points follow stack order, as in browsers.