Takumi

Helpers

Look up the helpers that build node trees, convert JSX and HTML, prepare images, and load fonts.

@takumi-rs/helpers builds node trees and loads fonts for render. Install it next to takumi-js, takumi-pdf, or a renderer binding:

npm install @takumi-rs/helpers
Build a node tree
import { ,  } from "@takumi-rs/helpers";

const  = ({
  : { : 32, : "white" },
  : [("Hello Takumi", { : 48 })],
});

Use it to build node trees or load fonts yourself. For JSX or HTML input, render and ImageResponse already convert the input and load its resources. takumi-js/helpers re-exports this package.

Fonts

HelperUse
googleFonts(options)Load Google Fonts families in one request. 1
fontFromUrl(url, options?)Turn a font URL into a lazy fonts entry. 2
subsetFonts({ fonts, source })Deprecated. 3

1 render keeps only the subsets the text uses. See Fonts & text.

2 options takes the fetch limits. Without them, pass the URL string in fonts instead.

3 subsetFonts is no longer needed, since a render keeps the subsets its text uses, the text inside SVG images included.

googleFonts, fontFromUrl, and prepareImages share fetch limits and retry behavior.

Building nodes

HelperReturns
container(props)A container node.
text(text, style?) / text(props)A text node.
image(props)An image node.
style(css)The same style object, typed.

The props argument holds the node's own fields. Node types lists them. Styles, presets, and stylesheet rules share the Declarations type. Custom properties such as "--accent": "red" accept strings or numbers, including in React's style prop.

Length and color shorthands return CSS strings. vw and vh are viewport units, em and rem are font-relative, and fr is a grid fraction. See the MDN CSS values reference.

rem resolves against the viewport's font size, not the outermost node. Units covers what each font-relative unit follows.

HelperOutput
percentage(50)50%
vw(100) / vh(100)100vw / 100vh
em(1.5) / rem(1.5)1.5em / 1.5rem
fr(1)1fr
rgba(0, 0, 0, 0.5)rgb(0 0 0 / 0.5)

Parsing templates

HelperImportUse
fromJsx(element, options?)@takumi-rs/helpers/jsxConvert JSX or a React element to { node, css }.
fromHtml(html)@takumi-rs/helpers/htmlConvert an HTML string to { node, css }.

fromJsx resolves React hooks and context without react-dom. Components that call useState, useContext, or use() render with server semantics: initial state, no effects. Preact trees work only when their components call no Preact hooks.

Images & emoji

HelperImportUse
prepareImages(options)@takumi-rs/helpersDeprecated. 1
extractEmojis(node, emojiType)@takumi-rs/helpers/emojiReplace emoji with CDN <img> nodes. 2

1 Use a renderer's prepare instead, which reads the images a document draws and fetches them.

2 takumi-js does this through its emoji option, so call it only on a renderer binding. See Emoji.

emojiType takes the CDN values of the emoji option listed in Image loading & emoji. It does not take from-font, which fetches nothing.

Last updated on