Node

takumi-js/node re-exports @takumi-rs/core — the native binding built per-platform via N-API. It loads only on runtimes with native module support (Node.js, Bun, Deno). For Workers, Vite, or the browser use takumi-js/wasm instead.

The native renderer is the fastest path and the only one that supports loadFontSync, font fallback, animation pipelines, and persistent image preloading at full throughput. Use it directly when you want to manage one renderer across many requests instead of paying construction cost per call.

Classes

`Renderer`

import {  } from "takumi-js/node";
import { ,  } from "takumi-js/helpers";

const  = new ({ : true });
.(new ());

const  = await .(({ : [("Hello")] }), {
  : 1200,
  : 630,
  : "png",
});

Methods on the Renderer instance:

Method	Returns	Purpose
`loadFontSync(font)`	`void`	Block on font registration. Safe at startup, not inside a handler.
`loadFont(font, signal?)`	`Promise<number>`	Register one font without blocking.
`loadFonts(fonts, signal?)`	`Promise<number>`	Register many fonts concurrently.
`render(node, options?, signal?)`	`Promise<Buffer>`	Render a node tree to a static image buffer.
`measure(node, options?, signal?)`	`Promise<MeasuredNode>`	Run layout only. See the Measure guide.
`renderAnimation(options, signal?)`	`Promise<Buffer>`	Sample a scene timeline at `fps` and encode WebP / APNG / GIF.
`encodeFrames(frames, options, signal?)`	`Promise<Buffer>`	Encode a precomputed frame sequence (each frame has its own node).
`putPersistentImage(source, signal?)`	`Promise<void>`	Add an image to the in-memory store referenced by `src` URL.
`clearImageStore()`	`void`	Drop every persistent image. Useful on memory-constrained hosts.

Options

`ConstructRendererOptions`

Prop

Type

Description

persistentImages?array

The images that needs to be preloaded into the renderer.

fonts?array

The fonts being used.

loadDefaultFonts?union

Whether to load the default fonts. If fonts are provided, this will be false by default.

`RenderOptions`

Prop

Type

Description

width?number

The width of the image. If not provided, the width will be automatically calculated based on the content.

height?number

The height of the image. If not provided, the height will be automatically calculated based on the content.

format?union

The format of the image.

quality?number

The quality of JPEG format (0-100).

drawDebugBorder?union

Whether to draw debug borders.

fetchedResources?array

The fetched resources to use.

stylesheets?array

CSS stylesheets to apply before rendering.

keyframes?union

Structured keyframes to register alongside stylesheets.

devicePixelRatio?number

The device pixel ratio.

timeMs?number

The animation timeline time in milliseconds.

dithering?union

The output dithering algorithm.

`RenderAnimationOptions`

Prop

Type

Description

scenesarray

The scenes to render sequentially.

drawDebugBorder?union

Whether to draw debug borders around layout elements.

widthnumber

The width of each frame in pixels.

heightnumber

The height of each frame in pixels.

format?union

The output animation format (WebP, APNG, or GIF).

quality?number

The quality of WebP format (0-100). Ignored for APNG and GIF.

fpsnumber

Frames per second for timeline sampling.

fetchedResources?array

The fetched resources to use.

stylesheets?array

CSS stylesheets to apply before rendering.

devicePixelRatio?number

The device pixel ratio.

`EncodeFramesOptions`

Prop

Type

Description

drawDebugBorder?union

Whether to draw debug borders around layout elements.

widthnumber

The width of each frame in pixels.

heightnumber

The height of each frame in pixels.

format?union

The output animation format (WebP, APNG, or GIF).

quality?number

The quality of WebP format (0-100). Ignored for APNG and GIF.

fetchedResources?array

The fetched resources to use.

stylesheets?array

CSS stylesheets to apply before rendering.

devicePixelRatio?number

The device pixel ratio.

Supporting types

`Font` / `FontDetails`

Prop

Type

Description

name?string

The name of the font. If not provided, the name in the font file will be used.

dataByteBuf

The font data.

weight?number

The weight of the font. If not provided, the weight in the font file will be used.

style?union

The style of the font. If not provided, the style in the font file will be used.

Font is FontDetails | Uint8Array | ArrayBuffer | Buffer. Passing raw bytes works when the font file contains its own metadata.

`MeasuredNode`

Prop

Type

Description

widthnumber

The measured width of the node.

heightnumber

The measured height of the node.

transformtuple

The transformation matrix of the node.

childrenarray

The children of the node.

runsarray

The text runs within the node.

`ImageSource`

Prop

Type

Description

srcstring

The source URL of the image.

dataunion

The raw image data (Uint8Array or ArrayBuffer).

`AnimationFrameSource` / `AnimationSceneSource`

Prop

Type

Description

nodeNode

The node tree to render for this frame.

durationMsnumber

The duration of this frame in milliseconds.

Prop

Type

Description

nodeNode

The node tree to render for this scene.

durationMsnumber

The duration of this scene in milliseconds.

On this page