DOCSEARCHbyAlgolia
Submit Docs

Takumi Documentation

repository·master·Indexed 25 days ago

https://github.com/kane50613/takumi

A high-performance Rust image rendering engine with Node.js bindings (takumi-js) that transforms node trees into assets like OG cards, banners, and animations without a headless browser. It supports static images (PNG, JPEG, WebP, ICO), vector SVG, and animations (GIF, APNG, WebP, H.265 MP4). Features include a layout engine using taffy, text shaping via parley and skrifa, and compatibility with Tailwind CSS, UnoCSS, and next/og API routes via ImageResponse.

Tokens
56.7K
Snippets
162
Records
318
Agent score
79%

What's inside Takumi

  1. Generate vector SVG output with takumi-svg

    master

    The takumi-svg package provides a way to render a node tree directly into real SVG elements (such as <rect>, <path>, <linearGradient>, etc.) instead of embedding a rasterized bitmap inside a data: URL. It uses quick_xml to build the document, ensuring all attributes and values are properly escaped.

    Supported features include:

    • Backgrounds & Borders: Backgrounds, borders, and border-radius (via backgrounds and clip).
    • Gradients: Linear and radial gradients; conic gradients are supported via a wedge-path approximation.
    • Effects: Box-shadow, filters, and backdrop-filter (using <filter> chains where the backdrop is the scene replayed up to the element).
    • Text: Glyph outlines, decorations, text-shadow, and -webkit-text-stroke.
    • Images & Glyphs: Bitmap and emoji glyphs, and embedded <image> elements.
    • Layout & Styling: Clip-path, overflow, opacity, and affine transforms.

  2. Use takumi-raster via the takumi umbrella

    master

    The takumi-raster crate provides a raster painting backend for takumi using tiny-skia. It includes canvas management, drawing primitives, filters, and a render entry point.

    To use this backend, access it through the takumi umbrella crate. The primary render functions are available at the umbrella's crate root, while the specific raster module is located at takumi::unstable::raster.

  4. Handle RTL and language-aware text

    master

    Takumi provides support for Right-to-Left (RTL) scripts (like Arabic and Hebrew) and locale-aware text shaping.

    RTL & Bidirectional Text

    Takumi handles mixed runs of RTL and LTR text. Note that the direction property controls the layout direction, but there is currently no manual override for the text run direction itself.

    Language-aware text

    Use the lang attribute to set the BCP-47 language for a node. This enables locale-aware shaping, such as Han unification (drawing different glyphs for the same code point based on whether the language is zh-Hans, zh-Hant, ja, or ko) and language-correct line breaking.

    • Per-node: Set lang on a specific element. Descendants inherit this value unless overridden.
    • Global: Pass lang as an option to the render function to set a default for the entire render.

    Note: Glyph changes only occur if the loaded font contains per-language variants (e.g., a pan-CJK font).

    <div>
  <p lang="ja">日本語</p>
  <p lang="zh-Hant">繁體中文</p>
</div>

  5. How Takumi differs from Satori

    master

    If you are migrating from Satori, note these key differences:

    • Layout Support: While Satori is limited to Flexbox, Takumi supports Flexbox, Grid, and standard block layout. A bare <div> in Takumi defaults to display: block.
    • Rendering Pipeline: Takumi rasterizes directly to the target format rather than returning an SVG that requires a secondary conversion step.

  7. Apply CSS to nodes in Takumi

    master

    Takumi provides four distinct ways to apply styling to elements during rendering:

    1. style prop: Use inline CSSProperties on a single node. This overrides the tag's default styles.
    2. tw prop: Apply Tailwind classes directly to a single node using the built-in parser.
    3. <style> tags: Include <style> tags inside your JSX. The engine automatically extracts these and processes them.
    4. stylesheets option: Pass an array of full CSS strings or imported stylesheets to the render or ImageResponse options. These are matched against className and id selectors.

  8. How Takumi's rendering pipeline works

    master

    Takumi converts templates (JSX, HTML, or JSON node trees) into a node tree consisting of container, image, and text nodes. The pipeline follows these stages:

    1. Layout: Uses taffy to handle Flexbox, CSS Grid, block, inline, float, calc(), absolute positioning, and z-index.
    2. Text Shaping: Uses parley and skrifa for WOFF/WOFF2 fonts, emoji, RTL, and multi-span inline blocks.
    3. Compositing: Handles stacking contexts, blend modes, filters, transforms, and SVG via resvg.
    4. Output: Encodes the result into various formats:
      • Statics: PNG, JPEG, WebP, ICO
      • Animations: GIF, APNG, WebP
      • Video: Raw RGBA frames
      • Vector: SVG

    A time axis is integrated into the pipeline, allowing CSS animations (@keyframes, animation shorthand, Tailwind utilities) to resolve correctly during rendering.

  9. Control variable axes and OpenType features

    master

    You can control variable font axes and OpenType features using standard CSS properties:

    • Variable Axes: Use font-variation-settings. For example, fontVariationSettings: "'opsz' 72, 'wght' 700".
    • OpenType Features: Use font-feature-settings (e.g., fontFeatureSettings: "ss01").
    • Shorthands: font-weight maps to the wght axis, and font-stretch maps to the wdth axis.

    To keep axes live, register a variable font without a specific weight.

    <div
  style={{
    fontFamily: "Fraunces",
    fontVariationSettings: "'opsz' 72, 'wght' 700",
    fontFeatureSettings: "ss01",
  }}
>
  Variable Font Text
</div>

  10. Understand Takumi Node Types

    master
    In Takumi, a node tree represents content and style using a plain JSON structure. Every node in the tree must be one of three types: container, text, or image. Because the tree only contains these nodes and their styles, it can be generated directly from structured-output schemas (like LLM outputs). Note that external resources like fonts, images, and specific output options are passed as separate arguments to the render function rather than being embedded in the node tree itself.

  11. How takumi-js selects a backend runtime

    master

    Takumi automatically detects your runtime to select the most efficient backend:

    • Node.js / Bun: Uses native @takumi-rs/core (via napi-rs).
    • Next.js Edge / Cloudflare Workers / Browsers: Uses @takumi-rs/wasm.

    You can manually override this behavior by providing a module option to the render() function or by importing takumi-js/wasm directly.

  12. Handle Chromium-parity user-agent styles in Takumi v2

    master

    Takumi v2 uses a Chromium-parity user-agent stylesheet, which introduces several changes to default element rendering:

    • Relative Keywords: font-weight: bolder / lighter and font-size: larger / smaller are now functional (they were ignored in v1).
    • Default Styles: Elements like lists, sub, sup, ins, del, form controls, details, summary, and search now carry default styles. If you require the v1 look, you must explicitly override these defaults in your CSS.