Introduction

Sone turns a tree of JavaScript function calls into pixel-perfect images and PDFs — without a browser, without a templating language, without a missing-feature-shaped hole somewhere in your CSS.

import { Column, Span, sone, Text } from "sone";

const card = Column(
  Text("Hello, ", Span("World").color("#0DF").weight("bold")).size(44),
  Text("A layout engine for image generation.").size(18).color("#9aa"),
)
  .gap(8)
  .padding(40)
  .bg("#0a0a0a");

await sone(card).jpg(); // → Buffer

That's the whole API surface: composable nodes (Column, Row, Text, Photo, Table, …) with a fluent, typed builder. Sone runs the layout, paints to a canvas, and hands you a buffer.

What Sone is for

Programmatic document and image generation at scale. Invoices. Multi-page reports. Resumes. Certificates. Open Graph images. App UI snapshots. Anything that needs to look right when a machine renders it, repeatedly, in milliseconds.

If you're rendering one document for a human to read in a browser, you don't need Sone — write HTML. If you're rendering ten thousand documents an hour to a queue, or a single multi-page PDF that has to look exactly right every time, that's the gap Sone is built for.

Why not just use HTML?

HTML and CSS are markup. Markup doesn't render anything — it describes a document and hands it to a rendering engine. The only rendering engines that fully implement HTML and CSS are browser engines: Blink, WebKit, Gecko. There are no others. Each is a decades-long accretion of specs you don't need to put pixels in a JPG: a JavaScript runtime, a network stack, history and navigation, IME and a11y trees, video and WebGL, autoplay and content-security policies, scrollbar quirks, focus rings, dozens of CSS features layered on top of dozens more.

Your invoice doesn't need any of that. It needs flexbox, text layout, a few drawing primitives, and a way to write the result to a buffer. So when you bend HTML into a batch document pipeline, you end up in one of two places:

The API surface is exactly what the engine supports. If a method exists, it works; if it doesn't, TypeScript tells you. There is no parity gap, because there is no translation layer.

What's in the box

• Flexbox & CSS Grid — the same mental model you already know, powered by yoga-layout.
• Rich text first-class — mixed-style spans, justification, decorations, drop shadows, per-glyph gradients.
• Bidirectional text — automatic RTL handling for Arabic and Hebrew, mixed paragraphs.
• Hyphenation in 80+ languages — Knuth–Liang patterns, no extra deps to install.
• Balanced line wrapping for headlines and pull quotes.
• Multi-page PDFs — automatic page breaking, repeating headers/footers, manual PageBreak().
• Six output formats — PNG, JPG, WebP, PDF, SVG, raw Canvas.
• Metadata API — every laid-out node, line, and segment carries its bounding box. Export YOLO or COCO datasets for ML training.

Where to start