Package Exports
- rollers
Readme
rollers 📦
Generate OpenGraph images from Typst templates with dynamic data.
Installation
npm install rollers
Requirements
You'll need the Typst binary installed on your system. Install it via:
# macOS
brew install typst
# Ubuntu/Debian
curl -fsSL https://typst.app/install.sh | sh
# Or download from https://github.com/typst/typst/releases
Quick Start
import { generate } from "rollers";
const result = await generate({
template: `
#set page(width: 1200pt, height: 630pt, fill: rgb("#1e293b"))
#set text(fill: white, font: "Inter", size: 48pt)
#place(center + horizon)[
#align(center)[
#text(size: 64pt, weight: "bold")[{{title}}]
#v(0.5em)
#text(size: 32pt)[by {{author}}]
]
]
`,
data: {
title: "Building Modern Web Apps",
author: "tasky",
},
});
if (result.success) {
console.log("OpenGraph image created at:", result.outputPath);
} else {
console.error("Generation failed:", result.error);
}
API Reference
generate(options)
Creates an OpenGraph image from a template and returns the result.
Options:
template
(string): Typst template with{{variable}}
placeholdersdata
(object): Values to substitute into template variablesoutputPath
(string, optional): Where to save the image (creates temp file if not specified)fontPaths
(string[], optional): Additional directories to search for fontsignoreSystemFonts
(boolean, optional): Skip system fonts when renderingdpi
(number, optional): Output resolution in pixels per inchtypstBinaryPath
(string, optional): Custom path to typst binary
Returns: Promise resolving to GenerateResult
success
(boolean): Whether generation succeededoutputPath
(string): Path to generated image (only on success)error
(string): Error message (only on failure)
generateBuffer(options)
Same as generate()
but returns the image content as a Buffer instead of saving to disk.
Returns: Promise resolving to Buffer or null on failure
Template Variables
Use double curly braces to mark variables in your templates:
#set page(width: 1200pt, height: 630pt, fill: gradient.linear(..color.map.rainbow))
#set text(fill: white, font: "Inter", size: 36pt, weight: "bold")
#place(center + horizon)[
#align(center)[
{{title}}
#v(0.8em)
#text(size: 24pt)[Published on {{date}}]
#v(0.4em)
#text(size: 20pt)[{{category}}]
]
]
Variables can be strings, numbers, or booleans. The library will convert them to strings for substitution.
OpenGraph Image Dimensions
The standard OpenGraph image size is 1200x630 pixels (1.91:1 aspect ratio). This ensures your images look great when shared on social platforms like Twitter, Facebook, and LinkedIn:
#set page(width: 1200pt, height: 630pt)
Working with Fonts
Custom Font Paths
await generate({
template: '#set text(font: "My Custom Font")\nHello World',
data: {},
fontPaths: ["/path/to/fonts", "./project-fonts"],
});
System Fonts
By default, Typst can access system fonts. To disable this:
await generate({
template: "Content here",
data: {},
ignoreSystemFonts: true,
fontPaths: ["./fonts"], // Must provide custom fonts when ignoring system fonts
});
Advanced Usage
Custom DPI
Higher DPI creates sharper images but larger file sizes:
await generate({
template: `
#set page(width: 1200pt, height: 630pt)
#set text(size: 48pt)
Sharp OpenGraph image
`,
data: {},
dpi: 300, // Default is usually 144
});
Custom Typst Binary
If typst isn't in your PATH or you want to use a specific version:
await generate({
template: "Content",
data: {},
typstBinaryPath: "/usr/local/bin/typst",
});
Error Handling
const result = await generate({
template: "Hello {{missingVar}}",
data: { name: "World" },
});
if (!result.success) {
console.error("Failed to generate image:", result.error);
// Error: Template variable 'missingVar' not found in data
}
Class-based API
For more control, use the Generator
class directly:
import { Generator } from "rollers";
const result = await Generator.generate(options);
const buffer = await Generator.generateBuffer(options);
License
MIT