takumi-usage

name	takumi-usage
description	Guidelines, syntax, templates, API usage, and styling best practices for rendering static/animated images and vector SVG using Takumi.

Takumi Usage & Best Practices

All-in-one guide for rendering with Takumi. Built-in layout rules, advanced styles, and performance.

JS / TS API Reference

1. Static Render (render & renderSvg)

Renders JSX templates, HTML strings, or JSON node trees to raster buffers (PNG/JPEG/WebP) or vector SVG markup.

import { render, renderSvg } from "takumi-js";

// Renders dynamic JSX layout directly to PNG bytes
const pngBuffer = await render(
  <div tw="w-full h-full bg-zinc-950 flex items-center justify-center">
    <h1 tw="text-white text-6xl">Takumi Engine</h1>
  </div>,
  {
    width: 1200,
    height: 630,
    format: "png", // "png" | "jpeg" | "webp"
    quality: 90    // (Optional) For JPEG/WebP formats
  }
);

// Renders to responsive XML SVG string containing glyph path vector data
const svgString = await renderSvg(
  <div tw="w-full h-full bg-zinc-900">
    <span tw="text-white">Scalable Vector</span>
  </div>,
  { width: 800, height: 400 }
);

2. Animated Render (renderAnimation)

Compiles sequences of scenes into animated WebP, GIF, or APNG buffers.

import { renderAnimation } from "takumi-js";

const animatedBuffer = await renderAnimation({
  width: 400,
  height: 400,
  fps: 30,
  format: "webp", // "webp" | "gif" | "apng"
  quality: 80,    // Compression quality (0-100)
  scenes: [
    {
      durationMs: 1500,
      node: (
        <div tw="w-full h-full bg-black flex items-center justify-center">
          <div tw="w-24 h-24 bg-rose-500 animate-bounce rounded-full" />
        </div>
      )
    }
  ]
});

3. Edge / Framework Integration (ImageResponse)

A next/og compatible handler designed for Edge runtimes, Cloudflare Workers, Next.js API endpoints, and standard HTTP server frameworks.

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

export function GET() {
  return new ImageResponse(
    <div tw="w-full h-full bg-slate-900 flex items-center justify-center">
      <h1 tw="text-white text-5xl">Dynamic OG Card</h1>
    </div>,
    {
      width: 1200,
      height: 630
    }
  );
}

4. Parsing Helpers (takumi-js/helpers/*)

Low-level utilities for compiling layout elements without executing the full renderer.

import { fromHtml } from "takumi-js/helpers/html";
import { fromJsx } from "takumi-js/helpers/jsx";

// Converts raw HTML template string into JSON layout node tree
const htmlNodeTree = fromHtml(
  "<div class='flex'><span>Hello</span></div>",
  { max_depth: 512 }
);

// Compiles React ReactNode elements into JSON layout node tree
const jsxNodeTree = fromJsx(
  <div tw="flex"><span>Hello</span></div>
);

---

Options Configuration (RenderOptions)

• fonts: An array of custom fonts [{ name, url, weight, style }]. Values can point to remote URLs (WOFF2/WOFF/TTF), local file paths, or binary Node.js Buffer arrays.
• emoji: Configures the emoji fallback strategy: "twemoji" (default), "blob-emoji", "openmoji", "noto-emoji", or "from-font" (uses custom loaded font glyphs).
• images: Option to pass pre-fetched image arrays [{ url, buffer }] or supply a shared caching fetch-client configuration.
• stylesheets: An array of raw global CSS string sheets to inject into the rendering layout context.

---

Hidden Layout Capabilities (Deep-Dive)

1. Auto-scaling Text (text-fit)

Automatically scales font-size to fit the containing inline line-box width, avoiding clipping or wrapping.

• Syntax: text-fit: [ none | grow | shrink ] [ consistent | per-line | per-line-all ]? [percentage]?
• Example: tw="text-fit-grow-consistent" or style={{ textFit: "grow consistent 120%" }}.

2. CSS Motion Paths (offset-path)

Enables complex placement and animation sequences of elements along custom vector paths or geometric rays.

• Properties: offset-path, offset-distance (percentage), offset-rotate (angle / auto).
• Syntax: ray(<angle> <size> contain? at <position>?) or path("<svg path command>") or basic shapes (circle(), polygon(), inset()).

3. OpenType Typography Settings

Provides fine-grained control over font rendering features and variable layout configurations.

• font-variation-settings: Configures variable font axis settings (e.g. "'wght' 750, 'wdth' 90").
• font-feature-settings: Enables OpenType font ligatures, kerning, and variants (e.g. "'ss01' 1, 'kern' 1").

4. Custom Filters & Graphics

• filter: Supports blur(), brightness(), contrast(), drop-shadow(), grayscale(), hue-rotate(), invert(), opacity(), saturate(), sepia().
• mix-blend-mode & background-blend-mode: Layer blending modes (e.g. multiply, screen, overlay).
• backdrop-filter: Applies filter effects to elements behind the container.
• clip-path: Clips elements via shapes: polygon(...), circle(...), inset(...).

5. Layout Defaults

• CSS Grid support: Supports grid-cols-X, gap-X, flex, and block layout.
• Tag Presets: Custom HTML styles are pre-mapped for tags: h1–h6, div, pre (keeps space layout), strong, em, blockquote, and hr.
• Line Breaks: <br> tags parse to \n in text elements automatically.

---

Rust Crate API (takumi)

use takumi::prelude::*;
use takumi::render;

let node = Node::container([Node::text("Hello, world!").with_style(
  Style::default().with(StyleDeclaration::font_size(Length::Px(32.0).into())),
)]);

let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
  "../../assets/fonts/geist/Geist[wght].woff2"
)))?;

let options = RenderOptions::builder()
  .viewport(Viewport::new((1200, 630)))
  .node(node)
  .fonts(&fonts)
  .build();

let image = render(options)?;

To build the node tree from HTML instead, enable the from-html feature and use from_html:

use takumi::prelude::*;
use takumi::{from_html, render};

let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
  "../../assets/fonts/geist/Geist[wght].woff2"
)))?;

let html = r#"<div style="background: red; width: 100%; height: 100%;"></div>"#;
let node = from_html(html, FromHtmlOptions::default())?;

let options = RenderOptions::builder()
  .viewport(Viewport::new((1200, 630)))
  .node(node)
  .fonts(&fonts)
  .build();

let image = render(options)?;