Type Definitions - OGify | Generate beautiful Open Graph images in minutes

Complete TypeScript type definitions for the @ogify/core library. These types provide full type safety when creating templates and configuring renderers.

Core Types

OgTemplateParams

Base type for template parameters. All template parameter types should extend this.

type OgTemplateParams = Record<string, string | string[] | number | boolean>;

Parameters are the data that gets injected into templates to create personalized OG images. Values can be:

Strings: Text content (titles, descriptions, names)
String Arrays: Lists of tags, categories
Numbers: Counts, dates, metrics
Booleans: Flags, toggles, states

const params: OgTemplateParams = {
  title: "My Blog Post",
  author: "John Doe",
  views: 1234,
  published: true,
  tags: ["typescript", "web development"],
};

OgTemplate

Complete definition of an Open Graph image template. A template is a reusable blueprint for generating OG images.

type OgTemplate<TParams = OgTemplateParams> = {
  renderer: (
    props: OgTemplateOptions & { params: TParams }
  ) => string | ReactNode | Promise<string | ReactNode>;
  fonts: OgFontConfig[];
  emojiProvider?: OgEmojiProvider;
};

renderer

function

required

Function that generates the template output. Receives OgTemplateOptions & { params: TParams } and can return:

ReactNode — JSX element tree passed directly to Satori (recommended)
string — HTML string parsed with satori-html before Satori
Promise of either — async renderers are fully supported

Renderer context props:

Prop	Type	Default	Description
`params`	`TParams`	—	Merged template parameters
`width`	`number`	`1200`	Canvas width (original, not scaled)
`height`	`number`	`630`	Canvas height (original, not scaled)
`fonts`	`OgFontConfig[]`	template fonts	Font override from render options
`emojiProvider`	`OgEmojiProvider`	template default	Emoji provider override
`isRTL`	`boolean`	`false`	Right-to-left layout
`scale`	`number`	`1`	Supersampling factor (do not use for layout)

See Rendering Pipeline for details.

Returning null or undefined at the root will throw a clear error instead of silently failing later in the Satori pipeline.

Satori does not support dangerouslySetInnerHTML. For inline styled text in JSX templates, use htmlSnippet to parse trusted HTML fragments into Satori-compatible flex word containers.

fonts

OgFontConfig[]

required

Custom fonts to use in this template. Must be a non-empty array — validateTemplate throws at registration time if fonts is missing.

emojiProvider

OgEmojiProvider

Optional emoji provider to use in this template. If not specified, defaults to 'noto'.

OgTemplateRenderer

Configuration for the TemplateRenderer class. Defines available templates, global defaults, and lifecycle hooks.

type OgTemplateRenderer<
  TMap extends Record<string, OgTemplateParams> = Record<
    string,
    OgTemplateParams
  >
> = {
  templates: { [K in keyof TMap]: OgTemplate<TMap[K]> };
  sharedParams?:
    | Partial<TMap[keyof TMap]>
    | (() => Promise<Partial<TMap[keyof TMap]>>);
  cache?: OgCacheConfig;
  beforeRender?: (
    templateId: keyof TMap,
    params: TMap[keyof TMap]
  ) => void | Promise<void>;
  afterRender?: (
    templateId: keyof TMap,
    params: TMap[keyof TMap],
    imageBuffer: Buffer
  ) => void | Promise<void>;
};

templates

object

required

Map of template definitions to register, keyed by template ID

sharedParams

object | function

Shared parameter values applied to all templates. These values are merged with user-provided parameters, with user values taking precedence.

cache

OgCacheConfig

Cache configuration for fonts and icons. When provided, enables LRU caching to improve performance by reducing redundant network requests.

beforeRender

function

Hook called before rendering. Useful for logging, analytics, parameter validation, authentication checks, and rate limiting.

afterRender

function

Hook called after rendering. Useful for caching generated images, cleanup operations, sending notifications, and updating metrics.

Font Configuration

OgFontConfig

Configuration for a font used in OG image templates. Fonts can be loaded from three sources (in priority order):

Pre-loaded binary data (via data property)
Remote URL (via url property)
Google Fonts API (automatic detection based on name)

type OgFontConfig = {
  name: string;
  weight?: FontWeight;
  style?: FontStyle;
  url?: string;
  data?: Buffer | ArrayBuffer;
  format?: OgFontFormat;
};

name

string

required

The font family name (e.g., ‘Inter’, ‘Roboto’, ‘Merriweather’)

weight

number

default:400

Font weight (100-900)

style

'normal' | 'italic'

default:"normal"

Font style

url

string

URL to the font file (for custom/self-hosted fonts)

data

Buffer | ArrayBuffer

Pre-loaded font binary data

format

'woff' | 'ttf'

default:"woff"

Font file format

const font1: OgFontConfig = {
  name: "Inter",
  weight: 400,
  style: "normal",
};

const font2: OgFontConfig = {
  name: "CustomFont",
  url: "https://example.com/font.woff2",
  weight: 700,
};

const font3: OgFontConfig = {
  name: "MyFont",
  data: fontBuffer,
  weight: 400,
};

OgFontFormat

Supported font file formats.

type OgFontFormat = "woff" | "ttf";

woff: Web Open Font Format (modern, compressed)
ttf: TrueType Font (legacy, larger file size)

Template Options

OgTemplateOptions

Props passed to the template renderer function, merged with params. Also available as options in renderToImage.

type OgTemplateOptions = {
  fonts?: OgFontConfig[];
  emojiProvider?: OgEmojiProvider;
  width?: number;
  height?: number;
  isRTL?: boolean;
  scale?: number;
};

The renderer is always called as:

template.renderer({ params, ...options, width, height });

Templates always receive the original width/height values. The scale option only affects Resvg rasterization — not Satori layout. See Scale & Supersampling.

fonts

OgFontConfig[]

Custom fonts to use in this template

emojiProvider

OgEmojiProvider

Optional emoji provider to use in this template

width

number

default:1200

Optional custom width in pixels. Templates always receive the original width/height values — scale is applied at the rasterisation step.

height

number

default:630

Optional custom height in pixels

isRTL

boolean

default:false

Enable Right-to-Left text direction

scale

number

default:1

Supersampling scale factor for higher-quality PNG output. Satori renders the SVG at the original width × height; Resvg then rasterises it at width × scale pixels wide.

`scale`	Output dimensions	Notes
`1` (default)	1200 × 630	No change — fully backward compatible
`1.25`	1500 × 787	Mild quality boost
`1.5`	1800 × 945	Good quality / size balance
`2`	2400 × 1260	Recommended — @2x retina
`3`	3600 × 1890	@3x ultra
`4`	4800 × 2520	Maximum (clamped)

Constraints:

Float values are supported (1.25, 1.5, etc.)
Values below 1 are clamped to 1
Values above 4 are clamped to 4 (prevents OOM)
Output PNG file size increases proportionally to scale²

renderer: ({ params, width, height, isRTL }) => (
  <div
    tw="flex flex-col w-full h-full"
    style={{ width, height }}
  >
    <div tw="text-[64px] font-bold">{params.title}</div>
    <div tw="text-[28px]">{params.description}</div>
  </div>
),

renderer: ({ params, width, height }) => `
  <div style="width: ${width}px; height: ${height}px">
    <h1>${params.title}</h1>
    <p>${params.description}</p>
  </div>
`,

Emoji Providers

OgEmojiProvider

Supported emoji providers for rendering emoji characters in OG images. Each provider offers a different visual style.

type OgEmojiProvider =
  | "twemoji"
  | "fluent"
  | "fluentFlat"
  | "noto"
  | "blobmoji"
  | "openmoji";

twemoji

Twitter’s emoji set - colorful, rounded style

fluent

Microsoft’s Fluent emoji - 3D style with color

fluentFlat

Microsoft’s Fluent emoji - flat 2D style

noto

Google’s Noto Color Emoji - current standard (default)

blobmoji

Google’s blob-style emoji - deprecated but still available

openmoji

Open-source emoji with outlined style

Utility Types

OgTemplateRenderResult

Return type of a template renderer function.

type OgTemplateRenderResult = string | ReactNode;

ReactNode — passed directly to Satori (JSX templates)
string — parsed with satori-html, then passed to Satori

HtmlSnippetOptions

Options for htmlSnippet word-container layout.

type HtmlSnippetOptions = {
  justify?: "flex-start" | "center" | "flex-end";
  gap?: number;
  fontSize?: number;
};

justify

'flex-start' | 'center' | 'flex-end'

default:"flex-start"

Flex main-axis alignment for the word container.

gap

number

Gap between word items in pixels. Overrides the font-size-derived default.

fontSize

number

Font size in pixels. Used to derive gap when gap is omitted (~29% of font size).

Caching

OgCacheConfig

Cache configuration for fonts and icons. Supports two caching strategies: memory and filesystem.

type OgCacheConfig =
  | {
      type: "memory";
      ttl?: number;
      max?: number;
    }
  | {
      type: "filesystem";
      dir?: string;
      ttl?: number;
      max?: number;
    };

Memory Cache
Filesystem Cache

Fast in-memory cache with LRU eviction

type

'memory'

required

Memory-based caching strategy

ttl

number

default:3600000

Time-to-live in milliseconds (default: 1 hour)

max

number

default:100

Maximum number of items to cache

const cache: OgCacheConfig = {
  type: 'memory',
  ttl: 3600000, // 1 hour
  max: 100
};

Persistent cache stored on disk

type

'filesystem'

required

Filesystem-based caching strategy

dir

string

default:".ogify-cache"

Directory to store cache files

ttl

number

default:3600000

Time-to-live in milliseconds (default: 1 hour)

max

number

default:100

Maximum number of items to cache

const cache: OgCacheConfig = {
  type: 'filesystem',
  dir: '.cache/ogify',
  ttl: 7200000, // 2 hours
  max: 200
};

​Core Types

​OgTemplateParams

​OgTemplate

​OgTemplateRenderer

​Font Configuration

​OgFontConfig

​OgFontFormat

​Template Options

​OgTemplateOptions

​Emoji Providers

​OgEmojiProvider

​Utility Types

​OgTemplateRenderResult

​HtmlSnippetOptions

​Caching

​OgCacheConfig

Core Types

OgTemplateParams

OgTemplate

OgTemplateRenderer

Font Configuration

OgFontConfig

OgFontFormat

Template Options

OgTemplateOptions

Emoji Providers

OgEmojiProvider

Utility Types

OgTemplateRenderResult

HtmlSnippetOptions

Caching

OgCacheConfig